@senad-d/branchme 0.1.7 → 0.1.8

package/CHANGELOG.md

@@ -1,13 +1,16 @@
 # Changelog
 
-## 0.1.0 - Unreleased
+## 0.1.8 - Unreleased
 
 - Implemented the `branchme` informational slash command with help aliases.
-- Added strict BranchMe tools: `branch_status`, `change_branch`, `fetch_branch`, `pull_branch`, `rebase_branch`, `create_branch`, `push_branch`, and `pull_request`.
-- Added argv-style git helpers for repository status, branch validation/creation/switching, clean-worktree preflight, upstream detection, configured-upstream fetch, fast-forward-only current-branch pull, current-branch rebase with automatic abort on failure, and current-branch push/publish.
+- Added strict BranchMe tools: `branch_status`, `change_branch`, `fetch_branch`, `pull_branch`, `rebase_branch`, `create_branch`, `push_branch`, `pull_request`, `list_worktrees`, `create_worktree`, and `remove_worktree`.
+- Added argv-style git helpers for repository status, branch validation/creation/switching, clean-worktree preflight, upstream detection, configured-upstream fetch, fast-forward-only current-branch pull, current-branch rebase with automatic abort on failure, current-branch push/publish, and bounded NUL-delimited worktree discovery.
+- Added verified linked-worktree creation for a new branch from current `HEAD` or an unoccupied existing local branch, returning a structured ready handoff with the exact canonical absolute cwd and local branch for a caller-managed separate agent session.
+- Added force-free removal for exact, verified, clean linked worktrees while preserving and re-verifying the local branch at its captured commit; main, current, dirty, ignored-entry-containing, detached, locked, prunable/missing, bare, and foreign worktrees are rejected.
+- Added canonical absolute-path and lossless-identity validation before worktree mutations, including existing-destination, nested-worktree, common-Git-directory, repository-membership, redaction, escaping, and truncation boundaries. BranchMe does not copy ignored/untracked files or start/switch Pi sessions.
 - Added GitHub repository resolution, environment-token and local `.env` token fallback handling, REST pull request creation, response validation, and token redaction.
 - Added opt-in `BRANCHME_PR_AUTOFILL` support for omitted PR fields, including current/default branch inference, bounded, Markdown-safe, and token-redacted title/body generation from commit subjects, and a non-draft default.
 - Added bounded automatic Git context before each agent run with branch/upstream state, working-tree counts and unstaged paths, authenticated related-open-PR lookup, and recent commits.
 - Expanded `branch_status` into a shared, explicit, read-only context refresh for state that may change during a run.
-- Added unit tests with mocked `pi.exec` and `fetch` for Git context collection and prompt safety, git helpers, GitHub helpers, command behavior, tool schemas, prompt metadata, and extension registration.
-- Updated public documentation for automatic context behavior, authenticated lookup and prompt-insertion security boundaries, package structure, and validation commands.
+- Added unit tests with mocked `pi.exec` and `fetch` for Git context collection and prompt safety, git and worktree helpers, GitHub helpers, command behavior, strict tool schemas, prompt metadata, and extension registration, plus isolated temporary-repository worktree lifecycle integration coverage.
+- Updated public documentation for automatic context behavior, authenticated lookup and prompt-insertion security boundaries, specialized Git-subagent worktree handoff, package structure, and validation commands.

package/README.md

@@ -10,13 +10,13 @@
 </p>
 
 <p align="center">
-  Current-repository branch and pull request tools for <a href="https://pi.dev">pi</a>.
-  <br />Inspect branch state, fetch, switch/create/pull/rebase branches, push, and open GitHub PRs from pi prompts.
+  Current-repository branch, worktree, and pull request tools for <a href="https://pi.dev">pi</a>.
+  <br />Inspect branch state, manage verified linked worktrees, update branches, push, and open GitHub PRs from pi prompts.
 </p>
 
 ---
 
-BranchMe is a Pi extension for safe branch workflow automation. Before each agent run, it appends a bounded, read-only snapshot of the current Git repository to the system prompt. It also adds an informational `/branchme` command and eight agent-callable tools that explicitly refresh state, switch to an existing local branch, fetch its configured upstream remote, fast-forward or rebase the clean current branch onto its upstream, create a branch from the current `HEAD`, push the current branch, and create a GitHub pull request.
+BranchMe is a Pi extension for safe branch and worktree workflow automation. Before each agent run, it appends a bounded, read-only snapshot of the current Git repository to the system prompt. It also adds an informational `/branchme` command and eleven agent-callable tools that refresh state, manage branches, inspect/create/remove linked worktrees, push the current branch, and create GitHub pull requests.
 
 <table align="center">
   <tr>
@@ -30,13 +30,14 @@ BranchMe is a Pi extension for safe branch workflow automation. Before each agen
 </table>
 
 - **Context-aware:** every agent run starts with bounded branch, working-tree, related-PR, and recent-commit metadata; repository metadata is untrusted data, not instructions.
-- **Current-repository only:** Git and GitHub operations are scoped to the checkout where pi is running; fetch, pull, and rebase resolve the current branch's configured upstream.
+- **Repository-scoped:** Git and GitHub operations resolve from the checkout where pi is running. Linked worktree directories may be outside that checkout, but must be verified members of the same repository.
 - **Explicit history rewrites:** `rebase_branch` runs only when explicitly requested, requires a clean current branch with an upstream, disables autostash and multi-ref updates, and automatically attempts to abort on failure.
+- **Verified worktree handoff:** `create_worktree` verifies path, branch, `HEAD`, and cleanliness before returning an absolute `handoff.cwd`; starting another Pi session or subagent there remains the caller's responsibility.
 - **Commit-safe:** context collection is read-only, and BranchMe never stages files, creates user-authored commits, generates commit messages, force-pushes, creates merge commits, resets, or edits files directly.
-- **Strict tools:** tool schemas reject extra properties such as `force`, `stash`, `discard`, `owner`, `repo`, `path`, or `baseRef`.
+- **Strict tools:** tool schemas reject extra properties such as `force`, `stash`, `discard`, `owner`, `repo`, `path`, or `baseRef`; worktree tools accept only their documented fields.
 - **PR-ready:** create GitHub pull requests from existing local branches after verifying the `headBranch` matches GitHub and the base is visible. PR fields can stay explicit, or configured autofill can derive omitted fields from the current branch, default branch, and commit subjects.
 
-> **Security:** pi packages run with your full system permissions. BranchMe runs local `git` commands, may make an automatic authenticated GitHub request to find a related open pull request, can fetch remotes, switch/create/pull/rebase branches, push the current branch, and create GitHub pull requests. Read [`SECURITY.md`](SECURITY.md).
+> **Security:** pi packages run with your full system permissions. BranchMe runs local `git` commands, may create or remove verified linked-worktree directories outside the active checkout, may make an automatic authenticated GitHub request to find a related open pull request, can update branches and remotes, and can create GitHub pull requests. Read [`SECURITY.md`](SECURITY.md).
 
 ## Table of Contents
 
@@ -89,9 +90,19 @@ A typical BranchMe flow is:
 7. Push the current branch with `push_branch`.
 8. After `push_branch` completes and GitHub can see the branches, create a pull request with `pull_request`.
 
+For isolated work, a specialized Git subagent can use the explicit worktree workflow:
+
+1. Call `list_worktrees` to inspect the current repository's bounded worktree inventory.
+2. Ask the user to provide or approve an exact absolute destination and call `create_worktree` with `branchMode: "new"` or `"existing"`.
+3. Wait for the result and require `details.handoff.ready === true`.
+4. Have the caller or orchestrator start a **separate** Pi session or subagent with its working directory set to the returned absolute `details.handoff.cwd`.
+5. After that session finishes, remove or preserve any staged, unstaged, untracked, unmerged, or ignored local files, then explicitly call `remove_worktree` if removal was requested. Removal retains the local branch.
+
+BranchMe does not change the active Pi process's cwd, start Pi or other processes, create sessions, copy `.env` or other ignored/untracked files, or delete branches. For credentials needed by agents in linked worktrees, prefer process-level environment variables rather than copying repository-root secrets.
+
 To refresh the current branch's configured remote-tracking ref without changing the local branch or working tree, use `fetch_branch`. To reconcile the clean current branch by rewriting its local commits, run `fetch_branch`, wait for it to complete, and then run `rebase_branch`. Both tools require a configured upstream; `rebase_branch` automatically attempts `git rebase --abort` if rebasing fails.
 
-BranchMe is tool-based. The slash command is informational only and never changes or updates branches, fetches, rebases, pushes, commits, stages, edits files, or opens pull requests.
+BranchMe is tool-based. The slash command is informational only and never changes or updates branches, creates or removes worktrees, changes cwd, starts processes/sessions, fetches, rebases, pushes, commits, stages, edits files, or opens pull requests.
 
 ---
 
@@ -213,6 +224,9 @@ Commands are informational only. BranchMe actions are performed by agent-callabl
 | Tool | Schema | Behavior |
 | --- | --- | --- |
 | `branch_status` | `{}` | Explicitly refreshes the same bounded context used at agent start: repo root in structured details, branch/detached state, upstream and ahead/behind counts, working-tree counts and unstaged/untracked paths, related open PR, and recent commits. It is read-only. |
+| `list_worktrees` | `{}` | Runs a bounded, read-only inventory of the current repository's main and linked worktrees, including path, branch/detached state, `HEAD`, current/main, locked, prunable, and omitted-entry details. Automatic Git context does not include this inventory. |
+| `create_worktree` | `{ "worktreePath": string, "branchName": string, "branchMode": "new" \| "existing" }` | Creates and verifies a linked worktree at an explicitly approved absolute path. `new` creates a local branch from current `HEAD`; `existing` requires an existing local branch not checked out elsewhere. It returns a ready handoff with the exact canonical absolute cwd and local branch identity. |
+| `remove_worktree` | `{ "worktreePath": string }` | Force-free removal of an explicitly selected, verified clean linked worktree. It rejects the main/current, detached, locked, prunable/missing, dirty, ignored-file-containing, or foreign worktree and verifies that the local branch remains at the same commit. |
 | `change_branch` | `{ "branchName": string }` | Validates `branchName`, requires `refs/heads/<branchName>` to exist locally, rejects dirty worktrees, and runs `git switch <branchName>`. |
 | `fetch_branch` | `{}` | Requires a current branch with a configured upstream and runs `git fetch --no-tags --no-recurse-submodules <upstream-remote> <upstream-branch-ref>:<remote-tracking-ref>`; only that tracking ref is refreshed without changing local branches or working-tree files. |
 | `pull_branch` | `{}` | Requires a clean current branch with a configured upstream and runs `git pull --ff-only --no-rebase --no-autostash <upstream-remote> <upstream-branch-ref>`; divergence fails without rebasing or creating a merge commit. |
@@ -221,7 +235,7 @@ Commands are informational only. BranchMe actions are performed by agent-callabl
 | `push_branch` | `{}` | Pushes the current branch to its configured upstream remote with an explicit `HEAD:<upstream-branch-ref>` refspec, or publishes it with `git push --set-upstream origin <currentBranch>` when no upstream exists. |
 | `pull_request` | `{ "headBranch"?: string, "baseBranch"?: string, "title"?: string, "body"?: string, "draft"?: boolean }` | Preflights GitHub branch visibility and verifies the GitHub `headBranch` commit matches the local branch, then creates a pull request in the resolved current repository. Omitted fields require `BRANCHME_PR_AUTOFILL=true`; branch refs must be distinct, exist locally, and cannot use `owner:branch`. |
 
-All schemas reject additional properties. `change_branch` never accepts `baseRef`, `force`, `stash`, `discard`, `create`, `owner`, `repo`, or path inputs. `fetch_branch`, `pull_branch`, and `rebase_branch` have strict empty schemas and never accept a branch, remote, refspec, force, autostash, or arbitrary rebase target. `pull_request` never accepts `owner`, `repo`, or owner-prefixed branch refs; BranchMe resolves the repository from local `origin` and/or matching `GITHUB_REPOSITORY`.
+All schemas reject additional properties. `change_branch` never accepts `baseRef`, `force`, `stash`, `discard`, `create`, `owner`, `repo`, or path inputs. `fetch_branch`, `pull_branch`, and `rebase_branch` have strict empty schemas and never accept a branch, remote, refspec, force, autostash, or arbitrary rebase target. `create_worktree` requires exactly `worktreePath`, `branchName`, and `branchMode`; `remove_worktree` requires exactly `worktreePath`. No worktree tool accepts force, move, prune, repair, lock, unlock, detached, orphan, remote, refspec, or arbitrary start-point controls. `pull_request` never accepts `owner`, `repo`, or owner-prefixed branch refs; BranchMe resolves the repository from local `origin` and/or matching `GITHUB_REPOSITORY`.
 
 ---
 
@@ -258,6 +272,44 @@ After push_branch completes, create a draft pull request from feature/docs-refre
 If pull request field autofill is enabled, after push_branch completes create a pull request and fill any details I did not provide.
 ```
 
+### Linked worktree verification and handoff
+
+`create_worktree` requires a non-blank absolute path with no control characters. Its immediate parent must already be a directory. BranchMe resolves that parent to build a canonical destination, rejects any existing file, directory, or symlink there, and rejects destinations inside a registered worktree or the repository's common Git directory. Before mutation, the canonical path and local branch must be returnable without redaction, escaping, Unicode alteration, or truncation: canonical paths are limited to 4,096 characters and branch identities to 512 characters, and credential-like token text is rejected. A dirty source worktree is allowed because creation does not switch or overwrite it.
+
+For `branchMode: "new"`, BranchMe creates the requested local branch from the current `HEAD` only. For `branchMode: "existing"`, it uses only an existing local branch that is not checked out in another worktree; it never infers a local branch from a remote. After Git succeeds, BranchMe re-lists worktrees and verifies the canonical path, local branch, `HEAD`, and clean checkout. A representative structured result subset is:
+
+```json
+{
+  "action": "create_worktree",
+  "handoff": {
+    "cwd": "/absolute/path/to/branchme-feature",
+    "branch": "feature/worktree-docs",
+    "head": "<full-commit-id>",
+    "ready": true,
+    "summary": "Worktree ready at /absolute/path/to/branchme-feature on branch feature/worktree-docs at <full-commit-id>."
+  }
+}
+```
+
+The full details also distinguish requested input from verified before/after state. Successful `handoff.cwd` and `handoff.branch` values are the exact identities verified against Git; BranchMe never substitutes `[REDACTED]`, escaped control sequences, or a truncation ellipsis in these machine-readable fields. Display content, summaries, and worktree inventory remain sanitized and bounded separately. An orchestrator may use `handoff.cwd` only after `ready` is `true`, and must start the next Pi session or subagent itself with that exact working directory. BranchMe never changes the active process's cwd or starts another process/session.
+
+`remove_worktree` canonicalizes the approved absolute path and requires an exact match in a fresh inventory for the current repository. It accepts only a present, unlocked, non-prunable, non-bare, branch-attached linked worktree that is neither main nor current, then rejects staged, unstaged, untracked, unmerged, or ignored entries. The canonical path and retained branch must pass the same pre-mutation lossless-identity checks used for creation. The ignored-entry preflight is bounded and does not return ignored paths. Removal uses `git worktree remove <verified-path>` without force, verifies the entry is gone, and returns the exact retained branch identity after confirming it still points to the captured commit:
+
+```json
+{
+  "action": "remove_worktree",
+  "handoff": {
+    "cwd": null,
+    "branch": "feature/worktree-docs",
+    "head": "<full-commit-id>",
+    "ready": false,
+    "summary": "Worktree directory /absolute/path/to/branchme-feature was removed; local branch feature/worktree-docs was retained at <full-commit-id>."
+  }
+}
+```
+
+Ignored and untracked files—including a repository-root `.env`—are not copied into a new linked worktree. Prefer credentials inherited through the new agent process environment. Git documents support for multiple worktrees of a superproject containing submodules as incomplete; BranchMe adds no force-based submodule cleanup. There is no force, move, prune, repair, lock, unlock, detached, orphan, or remote-inference worktree behavior.
+
 BranchMe operates only on the repository where pi is running:
 
 - Automatic collection and `branch_status` run bounded, read-only Git commands from the verified git root.
@@ -267,11 +319,14 @@ BranchMe operates only on the repository where pi is running:
 - `pull_branch` requires a clean worktree and configured upstream, updates only the current branch with `git pull --ff-only --no-rebase --no-autostash`, and has no branch, remote, force, or rebase input.
 - `rebase_branch` requires a clean worktree and configured upstream, rewrites only the current branch onto the locally available upstream with autostash and multi-ref updates disabled, and automatically attempts to abort on failure.
 - `create_branch` creates from the current `HEAD` only and has no `baseRef` input.
+- `list_worktrees` is an explicit, read-only repository inventory; it is intentionally absent from automatic active-worktree context.
+- `create_worktree` may create a linked checkout outside the active checkout only after canonical path and current-repository boundary checks; dependent worktree calls must wait for its verified handoff.
+- `remove_worktree` passes Git only a freshly verified canonical linked-worktree path, never uses force, and retains the branch.
 - `push_branch` pushes only the current branch, uses no bare upstream `git push`, and has no `branchName` input.
 - `pull_request` creates PRs only for the resolved current GitHub repository, requires resolved `headBranch` and `baseBranch` values to be distinct and exist locally, requires the GitHub `headBranch` commit to match the local branch, queues behind in-flight same-repository git mutation windows when possible, and rejects `owner:branch` head refs. Missing PR fields fail unless `BRANCHME_PR_AUTOFILL=true`.
 - If local `origin` and `GITHUB_REPOSITORY` both resolve but disagree, `pull_request` fails closed.
 
-BranchMe intentionally does **not** stage files, create user-authored commits, force checkout, stash changes, discard changes, force-push, create merge commits, edit files directly, or generate commit messages. Rebase-driven commit rewriting occurs only through explicit `rebase_branch` calls.
+BranchMe intentionally does **not** stage files, create user-authored commits, force checkout, stash changes, discard changes, force-push, create merge commits, edit files directly, copy ignored/untracked files between worktrees, delete branches during worktree removal, or generate commit messages. Rebase-driven commit rewriting occurs only through explicit `rebase_branch` calls.
 
 ---
 
@@ -316,7 +371,11 @@ Ensure the token and Git credentials have permission for the branch and pull req
 | Not a git repository | Start pi from inside a git checkout. |
 | Detached `HEAD` | Use `change_branch` to switch to an existing local branch, or checkout a branch before `fetch_branch`, `pull_branch`, `rebase_branch`, `create_branch`, or `push_branch`. |
 | Branch already exists | Choose a new local branch name for `create_branch`, or use `change_branch` to switch to it. |
-| Branch does not exist locally | Create a local branch first; `change_branch` does not checkout remote branches. |
+| Branch does not exist locally | Create a local branch first; `change_branch` and `create_worktree` existing mode do not infer local branches from remote branches. |
+| Worktree destination rejected | Provide an exact absolute path whose immediate parent exists; the destination must not exist or be inside another registered worktree or the repository's common Git directory. Its canonical path and branch identity must also fit the documented limits without credential-like token text or characters that require escaping. |
+| Existing worktree branch is occupied | Choose another existing local branch or remove its other linked checkout after cleaning it; BranchMe does not force multiple checkouts. |
+| Worktree removal rejected | Use `list_worktrees`, select a non-main/non-current linked worktree, and remove or preserve staged, unstaged, untracked, unmerged, and ignored files outside the checkout. Locked, detached, prunable/missing, bare, and foreign paths are not removable. |
+| Linked-worktree agent cannot find credentials | Pass credentials through the process environment. BranchMe does not copy repository-root `.env` or other ignored/untracked files. |
 | Dirty worktree before branch switch, pull, or rebase | Commit, stash, or discard changes outside BranchMe before using `change_branch`, `pull_branch`, or `rebase_branch`. |
 | Fetch, pull, or rebase has no upstream | Configure the current branch upstream outside BranchMe, then retry the tool. |
 | Pull is not a fast-forward | Run `fetch_branch`, wait for it to complete, then explicitly run `rebase_branch` if rewriting local commits is intended; otherwise reconcile outside BranchMe. |
@@ -344,7 +403,7 @@ npm run check:pack
 printf '/branchme help\n/quit\n' | pi --no-extensions -e .
 ```
 
-Validation covers TypeScript typechecking, formatting checks, automatic context collection and prompt injection, mocked GitHub lookup, unit tests, package checks, checkout Pi runtime smoke, and package-content verification. The checkout smoke loads BranchMe through Pi, then uses a temporary verifier command to confirm all eight BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata. Smoke-test notes are recorded in [`docs/SMOKE_TEST.md`](docs/SMOKE_TEST.md), and TUI/help captures are stored in [`docs/TUI_CAPTURE.md`](docs/TUI_CAPTURE.md).
+Validation covers TypeScript typechecking, formatting checks, automatic context collection and prompt injection, mocked GitHub lookup, isolated real-Git worktree lifecycle tests, package checks, checkout Pi runtime smoke, and package-content verification. The checkout smoke loads BranchMe through Pi, then uses a temporary verifier command to confirm all eleven BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata. Smoke-test notes are recorded in [`docs/SMOKE_TEST.md`](docs/SMOKE_TEST.md), and TUI/help captures are stored in [`docs/TUI_CAPTURE.md`](docs/TUI_CAPTURE.md).
 
 Refresh TUI captures intentionally with:
 
@@ -391,11 +450,13 @@ BranchMe publishes to npm as `@senad-d/branchme`. You need an npm account with p
 ```bash
 npm login
 npm whoami
-npm run release:check # optional preflight; the publish script runs this too
+npm run release:check # optional preflight; every publish path runs this gate
 node scripts/publish-npm.mjs
 ```
 
-The publish script requires a clean working tree, asks for the version number, runs `npm run release:check` (validation plus installed-package smoke), runs `npm version <version>` to update `package.json` and `package-lock.json`, creates the `v<version>` git tag, publishes with `npm publish --access public`, and then offers to push the release commit and tag.
+`npm run release:check` is the canonical release gate: it runs checkout validation and then installs and loads the packed npm artifact in isolation. Both the local publish script and the GitHub `Publish to npm` workflow run this gate before npm publication; a failure prevents publication and the workflow's Git tag creation.
+
+The publish script requires a clean working tree, asks for the version number, runs `npm run release:check`, runs `npm version <version>` to update `package.json` and `package-lock.json`, creates the `v<version>` git tag, publishes with `npm publish --access public`, and then offers to push the release commit and tag.
 
 Run it only from a clean working tree after updating `CHANGELOG.md`.
 

package/SECURITY.md

@@ -21,10 +21,12 @@ Implemented git mutations are limited to:
 - `pull_branch`: `git pull --ff-only --no-rebase --no-autostash <upstreamRemote> <upstreamBranchRef>` for the clean current branch after validating its configured upstream target.
 - `rebase_branch`: `git rebase --no-autostash --no-update-refs <upstream>` for the clean current branch after validating its configured upstream target. It rewrites local commits and automatically attempts `git rebase --abort` without the cancelled caller signal if the rebase fails or is killed.
 - `push_branch`: `git push <upstreamRemote> HEAD:<upstreamBranchRef>` for the current branch when an upstream exists, or `git push --set-upstream origin <currentBranch>` when no upstream exists.
+- `create_worktree`: `git worktree add -b <branchName> <canonicalPath> HEAD` for a new local branch, or `git worktree add <canonicalPath> <existingLocalBranch>` for an existing unoccupied local branch, after destination and repository-boundary validation.
+- `remove_worktree`: `git worktree remove <verifiedCanonicalPath>` without force, only after fresh repository-membership, safety-state, path, tracked/untracked status, and ignored-entry checks. The local branch is retained and verified at the same commit.
 
 Before each agent run, BranchMe also runs bounded, read-only Git commands to collect branch/upstream/ahead-behind state, working-tree counts, up to 20 unstaged or untracked path entries, and up to 5 recent commits. The same collector runs when `branch_status` explicitly refreshes context. Collection does not run `fetch`, `switch`, `pull`, `rebase`, `push`, `add`, `commit`, or any other mutation, and it never reads diffs or file contents.
 
-Branch switching, fast-forward pulls, and successful rebases can update working-tree files as normal Git behavior; fetch updates one validated remote-tracking ref without changing local branches or the working tree. Mutating branch operations for the same repository are serialized to avoid same-turn branch races. `pull_request` also uses the same repository queue around PR preflight and creation so it can wait behind an already-started same-repository mutation. BranchMe rejects dirty worktrees before `change_branch`, `pull_branch`, and `rebase_branch`. It does not force checkout, stash, stage files, create user-authored commits, reset, force-push, create merge commits, or edit files directly. Rebase-driven commit rewriting occurs only through an explicit `rebase_branch` call.
+Branch switching, worktree creation/removal, fast-forward pulls, and successful rebases can update or remove filesystem content as normal Git behavior; fetch updates one validated remote-tracking ref without changing local branches or the working tree. Mutating operations for the same repository are serialized to avoid same-turn races. `pull_request` also uses the same repository queue around PR preflight and creation so it can wait behind an already-started same-repository mutation. BranchMe rejects dirty worktrees before `change_branch`, `pull_branch`, and `rebase_branch`, and rejects any staged, unstaged, untracked, unmerged, or ignored entry in a linked worktree before removal. It does not force checkout/removal, stash, stage files, create user-authored commits, reset, force-push, create merge commits, or edit files directly. Rebase-driven commit rewriting occurs only through an explicit `rebase_branch` call.
 
 ## Network behavior
 
@@ -48,7 +50,10 @@ The branch preflight requests have no body. BranchMe uses the resolved `headBran
 BranchMe operates on the current repository only.
 
 - The GitHub repository is inferred from local `origin` and/or `GITHUB_REPOSITORY`.
-- Tool inputs never accept filesystem paths, `owner`, `repo`, or owner-prefixed `owner:branch` PR refs.
+- Branch and PR tools never accept filesystem paths, `owner`, `repo`, or owner-prefixed `owner:branch` PR refs. Worktree mutations accept only an explicitly approved absolute `worktreePath`, with `branchName` and `branchMode` additionally required for creation.
+- `list_worktrees` is read-only and returns a bounded inventory collected from `git worktree list --porcelain -z`; automatic Git context remains focused on the active worktree.
+- `create_worktree` accepts exactly `worktreePath`, `branchName`, and `branchMode` (`new` or `existing`). New mode uses current `HEAD` only; existing mode requires an existing local branch not checked out elsewhere and does not infer remote branches.
+- `remove_worktree` accepts exactly `worktreePath`, requires an exact canonical match in a fresh current-repository inventory, removes no branch, and does not accept force.
 - `change_branch` accepts only `branchName` and never creates branches, checks out remote branches, forces, stashes, or discards changes.
 - `fetch_branch` accepts no parameters, resolves the current branch's configured upstream remote and branch, constructs a source-to-remote-tracking refspec internally, disables tag fetching and submodule recursion, and does not prune or accept arbitrary refspecs.
 - `pull_branch` accepts no parameters, updates only the clean current branch from its configured upstream, and uses fast-forward-only semantics.
@@ -57,6 +62,16 @@ BranchMe operates on the current repository only.
 - Resolved PR branches are validated as distinct, existing local branch-name refs; identical or missing local branches and cross-repository `head` values are rejected before any GitHub request.
 - PR branch inputs must also be visible on GitHub before the PR is created, and `headBranch` must match the local branch commit; unpublished or stale `headBranch` values fail with guidance to run `push_branch`, wait for it to complete, and retry `pull_request`.
 
+## Worktree filesystem boundary
+
+Linked worktree management expands the mutation boundary beyond the active checkout. `create_worktree` may create a directory anywhere the user can write when the explicitly supplied destination passes all checks. BranchMe requires a non-blank absolute path without control characters, requires the immediate parent to exist as a directory, resolves that parent with `realpath`, and rejects any existing destination—including a symlink. It also rejects a destination inside any registered worktree or inside the current repository's common Git directory. Before mutation, the resulting canonical path and local branch must remain exactly identical as JavaScript strings after BranchMe's redaction, control/format escaping, Unicode-safe truncation, and size checks; the path limit is 4,096 characters and the branch limit is 512 characters.
+
+`remove_worktree` never passes an unverified user path to Git. It canonicalizes the supplied absolute path, requires an exact match in a fresh inventory belonging to the current repository, applies the same lossless checks to the canonical path and retained branch, and rejects the main worktree, the worktree containing the active Pi session, bare, detached, locked, prunable/missing, dirty, and ignored-entry-containing worktrees. A separate bounded porcelain scan detects ignored files and directories without exposing their paths or contents. After force-free removal, BranchMe verifies the worktree is no longer registered and that its local branch remains at the captured `HEAD`.
+
+Paths, branch names, lock/prune reasons, and Git output are untrusted metadata. Informational inventory, prose, summaries, and non-identity details are escaped, redacted, and bounded. Successful machine-readable `handoff.cwd` and handoff branch fields instead contain exact verified identities, so BranchMe rejects any identity that would require display transformation before mutation. This also applies to the retained branch returned after removal. Creation failures do not trigger automatic deletion of a possibly created directory or branch; the caller is told to inspect the repository and destination. No force, move, prune, repair, lock, unlock, detached, orphan, or remote-inference worktree operation is implemented.
+
+BranchMe does not copy ignored or untracked files, including repository-root `.env` files, into linked worktrees. If a caller creates ignored local files in a linked checkout, those files block removal until they are removed or preserved outside the checkout. Git documents support for multiple worktrees of a superproject containing submodules as incomplete; BranchMe does not add force-based submodule cleanup.
+
 ## Credentials
 
 Git fetch, pull, and push authentication is handled by the user's configured Git credential and transport setup. BranchMe never passes GitHub API tokens to Git commands.
@@ -68,6 +83,8 @@ Git fetch, pull, and push authentication is handled by the user's configured Git
 
 BranchMe also reads the non-secret `BRANCHME_PR_AUTOFILL` setting from the process environment or verified-root `.env`; all other `.env` keys are ignored. The `.env` reader uses async file I/O, requires a small regular file, and rejects directories, symlinks, special files, and oversized files. BranchMe does not read shell profiles, GitHub CLI credentials, or local credential stores. Token values are redacted from thrown errors, automatic context, generated PR text, tool content, and tool details.
 
+A newly created linked worktree does not receive the source checkout's `.env` or other ignored/untracked files. Start the separate agent with required credentials in its process environment rather than copying secrets into the linked checkout.
+
 ## System prompt boundary
 
 Automatic context is appended to Pi's system prompt before each agent run. Branch names, paths, Git status values, commit subjects, and GitHub PR metadata are repository-controlled, untrusted data and must never be interpreted as instructions. BranchMe redacts recognized token values, escapes control and format characters, quotes metadata, limits individual values to 512 characters by default, and limits the complete rendered snapshot to 4,000 characters. It further shortens values or omits entries when needed to enforce the total bound.
@@ -93,6 +110,7 @@ Do not open public issues for security-sensitive reports that include exploit de
 - Do not commit secrets, tokens, local `.env`, local `.pi/` state, or generated artifacts.
 - Keep tool schemas strict and reject unsupported fields.
 - Keep all git calls argv-style through `pi.exec("git", args)`.
-- Mock `pi.exec` and `fetch` in tests; do not touch real remotes.
+- Treat worktree paths as a filesystem security boundary; canonicalize them, verify current-repository membership before removal, and never add force cleanup.
+- Mock `pi.exec` and `fetch` in unit tests; use only temporary local repositories and directories for real-Git integration tests, and do not touch real remotes.
 - Keep package contents minimal with `npm run check:pack`.
 - Use isolated smoke tests with `pi --no-extensions -e .`.

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.8` 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,136 @@ 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, linked-worktree, push, and GitHub pull request workflows.
+- Tool count: eleven 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.
+  - 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, diff generation, stashing, resets, force pushes, or merge commits.
+  - 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 | Read-only |
+| 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/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, eleven tools, and automatic context hook.
+  - The context module owns bounded read-only collection, prompt formatting, and the `before_agent_start` hook.
+  - 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 Git helper owns argv-style current-repository inspection, branch/upstream workflows, worktree parsing/path validation/create/remove verification, and same-repository mutation serialization.
+  - 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 only.
+- Active-checkout mutations: explicit branch switching, creation, pull, and rebase 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, copy local-only files into new worktrees, delete the retained branch during removal, or mutate worktrees through slash commands.
+
+## 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. 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.
+- 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.
+
+## 9. 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.8` unreleased changes.
+- npm distribution uses package `@senad-d/branchme`; package-content checks exclude private specs, credentials, generated files, caches, and local state.
+
+## 10. 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`
+
+## 11. 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.
+- 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.