Orchestrata Ultimate / Specs / 064-git-worktree-tools

064-git-worktree-tools: Git Worktree Tools

This specification defines the Git Worktree Tools for the Orchestrata Ultimate system, providing capabilities to manage Git worktrees for parallel development workflows. The tools enable entering existing worktrees, creating new worktrees with optional branch creation, and exiting worktrees to return to the parent repository context.

At a glance

Reading this spec

This spec defines the Git worktree tools, which let agents and developers work on several features or fixes in parallel without switching branches in one working directory. Switching branches in place is disruptive and can lose uncommitted changes; Git worktrees let several working directories share one repository. The spec names two tools, EnterWorktreeTool (enter an existing worktree, or create a new one with an optional new branch) and ExitWorktreeTool (return to the main repository), and adds worktree discovery and validation, branch protection and conflict handling. Repository initialization and remote operations are explicitly out of scope.

The five user stories are entering an existing worktree, creating and entering a new one, exiting to the main repository, listing available worktrees and protected branch enforcement. The 54 requirement IDs (REQ-064-NNN) mostly restate the numbered functional requirements in order: the worktree path is a required parameter, an optional branch parameter creates a branch, resolved paths are normalized, the previous worktree is stored for restoration, exiting updates the session working directory to the main repository, force exit is supported, creation runs git worktree add, and branch names are validated. A group of security requirements (REQ-064-SEC-nnn) makes main, master, develop and HEAD protected by default so no worktree is created on them, lets the caller supply its own protected-branch list, and supports glob patterns through fnmatch.

The code is in the worktree tools module. The requirements traceability matrix lists each ID. The spec's own status line reads Complete and it tracks 3 files. Measured coverage is 50 of 54 requirements cited by at least one @traces in src/ (92.6%), spread over 1 module; the module citing the most of them is orchestrata_ultimate/tools/worktree_tools (50 requirements). In tests/, 0 requirements are cited by a test-side @traces. 4 requirements have no citing symbol; the behaviour may still exist in code that was never annotated.

Requirements

Checkbox is the state recorded in the requirements checklist; Traced by is the count of src/ symbols whose @traces names the ID.

Code that traces this spec

Checklists

checklists/requirements.md

The requirement list above comes from this file; 51 of 54 checkbox items are ticked.

Other tracked files

• specs/064-git-worktree-tools/compliance-audit.md

Full spec text

Verbatim from specs/064-git-worktree-tools/spec.md; headings are pushed down two levels.

SPEC-064: Git Worktree Tools

Metadata

• Spec ID: 064-git-worktree-tools
• Title: Git Worktree Tools - EnterWorktreeTool & ExitWorktreeTool
• Author: Mohamed
• Status: Complete
• Created: 2026-04-08
• Last Updated: 2026-04-08
• Priority: P0
• Version: 1.0.0

Overview

1.1 Purpose

This specification defines the Git Worktree Tools for the Orchestrata Ultimate system, providing capabilities to manage Git worktrees for parallel development workflows. The tools enable entering existing worktrees, creating new worktrees with optional branch creation, and exiting worktrees to return to the parent repository context.

1.2 Problem Statement

Developers often need to work on multiple features or bug fixes simultaneously. Switching between branches in a single working directory is disruptive and can lead to uncommitted changes being lost. Git worktrees provide a solution by allowing multiple working directories to share a single repository, enabling parallel work on different branches without directory switching.

1.3 Scope

The Git Worktree Tools provide:

• EnterWorktreeTool: Enter existing worktrees or create new ones
• ExitWorktreeTool: Return to the main repository worktree
• Worktree discovery and validation
• Branch protection enforcement
• Conflict detection and handling

1.4 Non-Scope

• Git repository initialization (covered by SPEC-001-git-init)
• Remote repository operations (covered by SPEC-001-git-remote)
• Branch merging/rebasing (covered by SPEC-001-git-merge)
• Commit history analysis (covered by SPEC-001-git-history)

User Scenarios

2.1 US-001: Enter Existing Worktree

As a developer
I want to enter an existing git worktree directory
So that I can continue working on a feature branch in an isolated environment

Preconditions:

• Main repository is initialized
• Worktree directory already exists
• Git worktree is registered in .git/worktrees

Flow:

1. User invokes EnterWorktreeTool with worktree path
2. Tool validates the path points to a valid worktree
3. Tool verifies worktree is registered in parent repository
4. Tool updates session context with new working directory
5. Tool returns success with worktree metadata

Postconditions:

• Session CWD is updated to worktree path
• Worktree branch information is available in context
• Git state reflects the worktree branch

Acceptance Criteria:

• [ ] AC-001: Tool accepts absolute and relative paths
• [ ] AC-002: Tool validates worktree exists on filesystem
• [ ] AC-003: Tool validates worktree is registered in .git/worktrees
• [ ] AC-004: Session context updates CWD to worktree path
• [ ] AC-005: Tool returns branch name and HEAD commit in response
• [ ] AC-006: Tool fails gracefully with clear error message if invalid

2.2 US-002: Create and Enter New Worktree

As a developer
I want to create a new worktree for a feature branch
So that I can start developing a new feature in isolation

Preconditions:

• Main repository is initialized
• User has branch creation permissions
• Target directory does not exist

Flow:

1. User invokes EnterWorktreeTool with worktree path, branch name, and create=true
2. Tool validates target directory does not exist
3. Tool checks branch doesn't already have a worktree
4. Tool runs git worktree add <path> <branch>
5. Tool creates branch if create_branch=true and branch doesn't exist
6. Tool updates session context with new working directory
7. Tool returns success with worktree metadata

Postconditions:

• New worktree directory exists at specified path
• Branch is checked out in new worktree
• Session CWD is updated to new worktree path

Acceptance Criteria:

• [ ] AC-007: Tool accepts create=true flag to enable creation
• [ ] AC-008: Tool creates branch if create_branch=true and branch missing
• [ ] AC-009: Tool supports specifying start_point (commit/branch)
• [ ] AC-010: Tool prevents creating worktree in existing directory
• [ ] AC-011: Tool prevents duplicate worktrees for same branch
• [ ] AC-012: Tool returns success with branch and path details

2.3 US-003: Exit Worktree to Main Repository

As a developer
I want to exit the current worktree and return to main repository
So that I can switch context to the primary branch

Preconditions:

• Current session is in a worktree (not main)
• Main worktree is accessible

Flow:

1. User invokes ExitWorktreeTool
2. Tool determines parent repository path
3. Tool verifies main worktree exists and is accessible
4. Tool updates session context with main repository CWD
5. Tool clears worktree-specific state
6. Tool returns success with main repository path

Postconditions:

• Session CWD is updated to main repository root
• Worktree-specific context is cleared
• Git state reflects main branch

Acceptance Criteria:

• [ ] AC-013: Tool correctly identifies parent repository
• [ ] AC-014: Tool updates session CWD to main repository
• [ ] AC-015: Tool clears worktree branch from context
• [ ] AC-016: Tool fails gracefully if main worktree unavailable
• [ ] AC-017: Tool works when called from main worktree (idempotent)

2.4 US-004: List Available Worktrees

As a developer
I want to see all available worktrees in the repository
So that I can choose which worktree to enter

Preconditions:

• Main repository is initialized
• At least one worktree exists (optional)

Flow:

1. User invokes ListWorktreesTool
2. Tool runs git worktree list to get all worktrees
3. Tool parses output and enriches with branch/HEAD info
4. Tool returns list of worktrees with metadata

Postconditions:

• User receives list of all worktrees with paths and branches

Acceptance Criteria:

• [ ] AC-018: Tool returns list of all worktrees
• [ ] AC-019: Each entry includes path, branch, and HEAD
• [ ] AC-020: Main worktree is marked distinctly
• [ ] AC-021: Tool handles repositories with no worktrees gracefully

2.5 US-005: Protected Branch Enforcement

As a project maintainer
I want to prevent worktree creation on protected branches
So that I can maintain branch integrity and compliance

Preconditions:

• Protected branch list is configured
• User attempts to create worktree on protected branch

Flow:

1. User attempts to create worktree with protected branch
2. Tool checks branch against protected list
3. Tool rejects creation with appropriate error
4. Tool logs security event

Postconditions:

• Protected branches cannot have worktrees created
• Security audit log is updated

Acceptance Criteria:

• [ ] AC-022: Main and master branches are protected by default
• [ ] AC-023: Custom protected branches can be configured
• [ ] AC-024: Tool returns clear error for protected branch
• [ ] AC-025: Security event is logged for protected branch attempts

Terminology

4.1 Worktree

A Git worktree is a separate working directory that shares the same Git repository with other worktrees. Each worktree can check out a different branch.

4.2 Main Worktree

The primary working directory created when a Git repository is initialized. Stored at the repository root.

4.3 Auxiliary Worktree

A secondary working directory created using git worktree add. Stored separately from the main repository.

4.4 Worktree Directory

The filesystem path where an auxiliary worktree's files are stored.

4.5 Parent Repository

The main Git repository that owns and manages all worktrees.

4.6 Protected Branch

A branch on which worktree creation is forbidden to maintain repository integrity.

Non-Functional Requirements

5.1 Performance Requirements

5.2 Scalability Requirements

5.3 Reliability Requirements

5.4 Usability Requirements

• All error messages must be human-readable
• Worktree paths must support tab completion
• Operations must be idempotent where possible
• User feedback provided within 100ms for all operations

Technical Design

6.1 Architecture Overview

The Git Worktree Tools follow a layered architecture:

┌─────────────────────────────────────┐
│         Session Layer              │
│    (SessionState Management)        │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│        Worktree Layer              │
│   (EnterWorktreeTool, ExitTool)    │
└─────────────────┬───────────────────┘
                  │
┌─────────────────▼───────────────────┐
│         Git Layer                  │
│      (GitPython API)               │
└─────────────────────────────────────┘

6.2 State Management

Session state tracks:

• Current working directory (CWD)
• Active branch
• Worktree history stack
• Git repository context

6.3 Context Switching Flow

Request → Validate → Execute → Update Context → Response
    ↓         ↓         ↓           ↓            ↓
  Input    Git    Command    Session      Output
 Validation Checks   Execution   Update     Formatting

6.4 Protected Branch Enforcement

Protected branch checks occur before worktree creation:

1. Parse protected branch configuration
2. Compile glob patterns to regex
3. Match branch name against patterns
4. Log security event if match found
5. Reject with PROTECTED_BRANCH error

Examples

7.1 Creating a Feature Branch Worktree

Request:

result = await tool.execute(
    worktreePath="/project/worktrees/feature-auth",
    branch="feature/authentication",
    create=True,
    createBranch=True,
    startPoint="main"
)

Response:

{
  "success": true,
  "worktree": {
    "path": "/project/worktrees/feature-auth",
    "branch": "feature/authentication",
    "head": "abc123def456789012345678901234567890abcd",
    "isMain": false,
    "isBare": false,
    "locked": false,
    "lockReason": null
  },
  "created": true,
  "message": "Created and entered worktree for feature/authentication"
}

7.2 Entering an Existing Worktree

Request:

result = await tool.execute(
    worktreePath="../worktrees/hotfix-login"
)

Response:

{
  "success": true,
  "worktree": {
    "path": "/project/worktrees/hotfix-login",
    "branch": "hotfix/login-bug",
    "head": "def456abc789012345678901234567890abcd123",
    "isMain": false,
    "isBare": false,
    "locked": false,
    "lockReason": null
  },
  "previousWorktree": {
    "path": "/project",
    "branch": "main",
    "head": "abc123def456789012345678901234567890abcd",
    "isMain": true
  },
  "created": false,
  "message": "Entered existing worktree for hotfix/login-bug"
}

7.3 Handling Protected Branch Error

Request:

result = await tool.execute(
    worktreePath="/project/worktrees/main-backup",
    branch="main",
    create=True
)

Response:

{
  "success": false,
  "error": "Cannot create worktree on protected branch: 'main'",
  "code": "PROTECTED_BRANCH",
  "details": {
    "branch": "main",
    "protectionReason": "Main branch must remain clean for production deployments"
  },
  "recoverySuggestions": [
    "Create a feature branch instead: git checkout -b feature/your-feature",
    "Work on the feature branch in a worktree"
  ]
}

7.4 Listing All Worktrees

Request:

result = await list_tool.execute(verbose=True)

Response:

{
  "success": true,
  "worktrees": [
    {
      "path": "/project",
      "branch": "main",
      "head": "abc123def456789012345678901234567890abcd",
      "isMain": true
    },
    {
      "path": "/project/worktrees/feature-auth",
      "branch": "feature/authentication",
      "head": "abc123def456789012345678901234567890abcd",
      "isMain": false
    }
  ],
  "count": 2,
  "message": "Found 2 worktrees"
}

Data Models

3.1 WorktreeInfo

Schema for representing a Git worktree:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://orchestrata.ult/worktree-info",
  "title": "WorktreeInfo",
  "description": "Represents a Git worktree with its metadata",
  "type": "object",
  "required": ["path", "branch", "head", "isMain"],
  "properties": {
    "path": {
      "type": "string",
      "description": "Absolute path to the worktree directory",
      "examples": ["/project/worktrees/feature-auth"],
      "pattern": "^/"
    },
    "branch": {
      "type": "string",
      "description": "Name of the branch checked out in this worktree",
      "examples": ["feature/authentication"],
      "pattern": "^[a-zA-Z0-9_./-]+$"
    },
    "head": {
      "type": "string",
      "description": "Full SHA-1 hash of the current HEAD commit",
      "examples": ["abc123def456789012345678901234567890abcd"],
      "pattern": "^[a-f0-9]{40}$"
    },
    "isMain": {
      "type": "boolean",
      "description": "Whether this is the main worktree (primary working directory)",
      "default": false
    },
    "isBare": {
      "type": "boolean",
      "description": "Whether this is a bare worktree",
      "default": false
    },
    "locked": {
      "type": "boolean",
      "description": "Whether the worktree is locked",
      "default": false
    },
    "lockReason": {
      "type": ["string", "null"],
      "description": "Reason for locking if locked",
      "examples": ["reason: ongoing work"]
    }
  }
}

3.2 EnterWorktreeRequest

Input schema for entering a worktree:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://orchestrata.ult/enter-worktree-request",
  "title": "EnterWorktreeRequest",
  "description": "Request parameters for entering a Git worktree",
  "type": "object",
  "properties": {
    "worktreePath": {
      "type": "string",
      "description": "Path to the worktree (absolute or relative to current directory)",
      "examples": ["../worktrees/feature-auth", "/project/worktrees/feature-auth"],
      "minLength": 1
    },
    "branch": {
      "type": ["string", "null"],
      "description": "Branch name for creating new worktree (required if create is true)",
      "examples": ["feature/new-login"],
      "pattern": "^[a-zA-Z0-9_./-]+$"
    },
    "create": {
      "type": "boolean",
      "description": "Whether to create the worktree if it doesn't exist",
      "default": false
    },
    "createBranch": {
      "type": "boolean",
      "description": "Whether to create the branch if it doesn't exist",
      "default": false
    },
    "startPoint": {
      "type": ["string", "null"],
      "description": "Commit or branch to start from when creating new branch",
      "examples": ["HEAD~3", "main", "abc123"],
      "pattern": "^[a-zA-Z0-9_./~-]+$"
    },
    "force": {
      "type": "boolean",
      "description": "Force creation even if worktree path exists (dangerous)",
      "default": false
    }
  },
  "required": ["worktreePath"],
  "additionalProperties": false
}

3.3 ExitWorktreeRequest

Input schema for exiting a worktree:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://orchestrata.ult/exit-worktree-request",
  "title": "ExitWorktreeRequest",
  "description": "Request parameters for exiting a Git worktree",
  "type": "object",
  "properties": {
    "force": {
      "type": "boolean",
      "description": "Force exit even if there are uncommitted changes in current worktree",
      "default": false
    },
    "stashChanges": {
      "type": "boolean",
      "description": "Automatically stash uncommitted changes before exiting",
      "default": false
    }
  },
  "additionalProperties": false
}

3.4 WorktreeListRequest

Input schema for listing worktrees:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://orchestrata.ult/worktree-list-request",
  "title": "WorktreeListRequest",
  "description": "Request parameters for listing Git worktrees",
  "type": "object",
  "properties": {
    "includePrunable": {
      "type": "boolean",
      "description": "Include prunable (orphan) worktrees in the list",
      "default": false
    },
    "verbose": {
      "type": "boolean",
      "description": "Include detailed information (HEAD, branch details)",
      "default": false
    }
  },
  "additionalProperties": false
}

3.5 EnterWorktreeResponse

Response schema for entering a worktree:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://orchestrata.ult/enter-worktree-response",
  "title": "EnterWorktreeResponse",
  "description": "Response from entering a Git worktree",
  "type": "object",
  "required": ["success", "worktree"],
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the operation succeeded"
    },
    "worktree": {
      "$ref": "#/$defs/WorktreeInfo"
    },
    "previousWorktree": {
      "$ref": "#/$defs/WorktreeInfo",
      "description": "Previous worktree information (if any)"
    },
    "created": {
      "type": "boolean",
      "description": "Whether a new worktree was created"
    },
    "message": {
      "type": "string",
      "description": "Human-readable status message"
    }
  },
  "$defs": {
    "WorktreeInfo": {
      "$ref": "https://orchestrata.ult/worktree-info"
    }
  }
}

3.6 ErrorResponse

Standard error response schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://orchestrata.ult/error-response",
  "title": "ErrorResponse",
  "description": "Standard error response for worktree operations",
  "type": "object",
  "required": ["success", "error", "code"],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "code": {
      "type": "string",
      "description": "Machine-readable error code",
      "examples": ["WORKTREE_NOT_FOUND", "PROTECTED_BRANCH", "INVALID_PATH"]
    },
    "details": {
      "type": ["object", "null"],
      "description": "Additional error context"
    },
    "recoverySuggestions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Suggestions for recovering from the error"
    }
  }
}

Functional Requirements

4.1 EnterWorktreeTool

4.1.1 Core Functionality

4.1.2 Path Resolution

4.1.3 Worktree Validation

4.1.4 Context Management

4.2 ExitWorktreeTool

4.2.1 Core Functionality

4.2.2 Safety Checks

4.2.3 Parent Repository Detection

4.3 CreateWorktreeTool

4.3.1 Core Functionality

4.3.2 Validation

4.4 ListWorktreesTool

4.4.1 Core Functionality

Error Conditions

10.1 Error Code Reference

10.2 Detailed Error Handling

10.2.1 ERR-001: NOT_A_GIT_REPO

Error ID: ERR-001

Condition: Current directory is not inside a git repository

Detection:

git rev-parse --is-inside-work-tree
# Returns "false" if not in repo

Response:

{
  "success": false,
  "error": "Not a git repository: /current/path",
  "code": "NOT_A_GIT_REPO",
  "recoverySuggestions": [
    "Navigate to a git repository directory",
    "Initialize a new git repository if needed: git init"
  ]
}

10.2.2 ERR-002: WORKTREE_NOT_FOUND

Error ID: ERR-002

Condition: Specified worktree path does not exist

Detection:

os.path.exists(request.worktreePath) == False

Response:

{
  "success": false,
  "error": "Worktree not found at path: /project/worktrees/feature-auth",
  "code": "WORKTREE_NOT_FOUND",
  "details": {
    "requestedPath": "/project/worktrees/feature-auth"
  },
  "recoverySuggestions": [
    "Create the worktree first: EnterWorktreeTool with create=true",
    "List available worktrees to see existing ones"
  ]
}

10.2.3 ERR-003: WORKTREE_NOT_REGISTERED

Error ID: ERR-003

Condition: Path exists but is not a registered git worktree

Detection:

# Check .git file points to worktree directory
git worktree list --porcelain | grep -q <path> == False

Response:

{
  "success": false,
  "error": "Path exists but is not a registered git worktree: /some/path",
  "code": "WORKTREE_NOT_REGISTERED",
  "recoverySuggestions": [
    "Use git worktree add to create a proper worktree",
    "This may be a regular directory that was accidentally created"
  ]
}

10.2.4 ERR-004: WORKTREE_ALREADY_EXISTS

Error ID: ERR-004

Condition: Worktree already exists at specified path

Detection:

os.path.exists(request.worktreePath) == True
# AND registered in git

Response:

{
  "success": false,
  "error": "Worktree already exists at: /project/worktrees/feature-auth",
  "code": "WORKTREE_ALREADY_EXISTS",
  "details": {
    "existingPath": "/project/worktrees/feature-auth"
  },
  "recoverySuggestions": [
    "Use EnterWorktreeTool without create flag to enter existing worktree",
    "Choose a different path for new worktree"
  ]
}

10.2.5 ERR-005: BRANCH_ALREADY_HAS_WORKTREE

Error ID: ERR-005

Condition: Attempting to create worktree for branch that already has one

Detection:

git worktree list | grep <branch>  # Branch has worktree

Response:

{
  "success": false,
  "error": "Branch 'feature/auth' already has a worktree",
  "code": "BRANCH_ALREADY_HAS_WORKTREE",
  "details": {
    "branch": "feature/auth",
    "existingWorktree": "/project/worktrees/feature-auth"
  },
  "recoverySuggestions": [
    "Enter the existing worktree: EnterWorktreeTool(worktree_path='/project/worktrees/feature-auth')",
    "Delete the existing worktree first if you want to create a new one"
  ]
}

10.2.6 ERR-006: BRANCH_NOT_FOUND

Error ID: ERR-006

Condition: Specified branch does not exist

Detection:

git show-ref --verify --quiet refs/heads/<branch> == False

Response:

{
  "success": false,
  "error": "Branch 'feature/nonexistent' does not exist",
  "code": "BRANCH_NOT_FOUND",
  "details": {
    "branch": "feature/nonexistent"
  },
  "recoverySuggestions": [
    "Enable createBranch=true to create the branch",
    "Specify a valid existing branch name",
    "Check branch name for typos"
  ]
}

10.2.7 ERR-007: PROTECTED_BRANCH

Error ID: ERR-007

Condition: Attempt to create worktree on protected branch

Detection:

branch in PROTECTED_BRANCHES  # main, master, release/*, etc.

Response:

{
  "success": false,
  "error": "Cannot create worktree on protected branch: 'main'",
  "code": "PROTECTED_BRANCH",
  "details": {
    "branch": "main",
    "protectionReason": "Main branch must remain clean for production deployments"
  },
  "recoverySuggestions": [
    "Create a feature branch instead: git checkout -b feature/your-feature",
    "Work on the feature branch in a worktree"
  ]
}

10.2.8 ERR-008: INVALID_PATH

Error ID: ERR-008

Condition: Path format is invalid

Detection:

# Contains null bytes, too long, or invalid characters
# os.path.normpath raises exception

Response:

{
  "success": false,
  "error": "Invalid path format: path contains invalid characters",
  "code": "INVALID_PATH",
  "details": {
    "providedPath": "/path/with\0null"
  },
  "recoverySuggestions": [
    "Provide a valid absolute or relative path",
    "Avoid special characters: null bytes, newlines"
  ]
}

10.2.9 ERR-009: PATH_OUTSIDE_REPO

Error ID: ERR-009

Condition: Worktree path would be outside repository structure

Detection:

# Resolve path and check it's within repo root
not path.resolve().is_within(repo_root)

Response:

{
  "success": false,
  "error": "Worktree path is outside repository bounds",
  "code": "PATH_OUTSIDE_REPO",
  "details": {
    "providedPath": "/tmp/worktree",
    "repoRoot": "/project"
  },
  "recoverySuggestions": [
    "Create worktree within repository: /project/worktrees/feature-name",
    "Use relative path from repository root"
  ]
}

10.2.10 ERR-010: UNCOMMITTED_CHANGES

Error ID: ERR-010

Condition: Current worktree has uncommitted changes

Detection:

git diff-index --quiet HEAD == False
git diff --stat == "" == False

Response:

{
  "success": false,
  "error": "Cannot exit worktree with uncommitted changes",
  "code": "UNCOMMITTED_CHANGES",
  "details": {
    "changedFiles": 3,
    "untrackedFiles": 1,
    "changes": [
      "M  modified_file.txt",
      "?? untracked.txt"
    ]
  },
  "recoverySuggestions": [
    "Commit your changes: git add . && git commit",
    "Stash changes: ExitWorktreeTool with stashChanges=true",
    "Force exit: ExitWorktreeTool with force=true (changes will remain)"
  ]
}

API Contracts

6.1 EnterWorktreeTool

6.1.1 Interface Definition

class EnterWorktreeTool(BaseTool):
    """Tool for entering or creating Git worktrees."""
    
    name: str = "EnterWorktreeTool"
    description: str = (
        "Enter an existing Git worktree or create a new one. "
        "Use this to switch to a different branch while maintaining "
        "an isolated working directory for parallel development."
    )
    version: str = "1.0.0"
    
    parameters: dict = {
        "type": "object",
        "properties": {
            "worktreePath": {
                "type": "string",
                "description": "Path to the worktree (absolute or relative). "
                              "If create=true, this is where the new worktree will be created.",
                "examples": [
                    "../worktrees/feature-auth",
                    "/project/worktrees/feature-auth",
                    "feature-branch"
                ]
            },
            "branch": {
                "type": ["string", "null"],
                "description": "Branch name to check out. Required if create=true.",
                "examples": ["feature/authentication", "bugfix/login-fix"],
                "default": None
            },
            "create": {
                "type": "boolean",
                "description": "Create worktree if it doesn't exist. Requires branch parameter.",
                "default": False
            },
            "createBranch": {
                "type": "boolean",
                "description": "Create branch if it doesn't exist. Requires create=true.",
                "default": False
            },
            "startPoint": {
                "type": ["string", "null"],
                "description": "Commit-ish (branch, tag, commit) to start new branch from. "
                              "Defaults to current HEAD if not specified.",
                "examples": ["HEAD~3", "v1.0.0", "main", "abc123def"],
                "default": None
            },
            "force": {
                "type": "boolean",
                "description": "Force creation even if directory exists (dangerous - may overwrite).",
                "default": False
            }
        },
        "required": ["worktreePath"],
        "additionalProperties": False
    }
    
    async def execute(
        self,
        worktreePath: str,
        branch: str | None = None,
        create: bool = False,
        createBranch: bool = False,
        startPoint: str | None = None,
        force: bool = False
    ) -> EnterWorktreeResponse:
        """Execute the worktree entry operation."""
        pass

6.1.2 Response Schema

class EnterWorktreeResponse(ToolResult):
    success: bool
    worktree: WorktreeInfo
    previousWorktree: WorktreeInfo | None = None
    created: bool = False
    message: str

6.1.3 Execution Flow

1. Validate current directory is in git repo
   └─> NOT_A_GIT_REPO if fails

2. Resolve worktreePath to absolute path
   └─> INVALID_PATH if resolution fails

3. If create == False:
   └─> Validate path exists
       └─> WORKTREE_NOT_FOUND if missing
   └─> Validate path is registered worktree
       └─> WORKTREE_NOT_REGISTERED if not

4. If create == True:
   └─> Validate branch parameter provided
       └─> BRANCH_REQUIRED if missing
   └─> Check protected branch list
       └─> PROTECTED_BRANCH if protected
   └─> Validate target directory doesn't exist (unless force)
       └─> WORKTREE_ALREADY_EXISTS if exists
   └─> Check branch doesn't already have worktree
       └─> BRANCH_ALREADY_HAS_WORKTREE if exists
   └─> Validate branch exists or createBranch == True
       └─> BRANCH_NOT_FOUND if missing and createBranch == False
   └─> Execute: git worktree add [options] <path> <branch>
       └─> GIT_COMMAND_FAILED if fails

5. Update session context:
   └─> Store previous CWD
   └─> Set new CWD to worktree path
   └─> Update branch context

6. Return EnterWorktreeResponse

6.2 ExitWorktreeTool

6.2.1 Interface Definition

class ExitWorktreeTool(BaseTool):
    """Tool for exiting current worktree to main repository."""
    
    name: str = "ExitWorktreeTool"
    description: str = (
        "Exit the current Git worktree and return to the main repository. "
        "This tool should be used when you want to switch context from a "
        "feature branch worktree back to the primary working directory."
    )
    version: str = "1.0.0"
    
    parameters: dict = {
        "type": "object",
        "properties": {
            "force": {
                "type": "boolean",
                "description": "Force exit even with uncommitted changes.",
                "default": False
            },
            "stashChanges": {
                "type": "boolean",
                "description": "Stash uncommitted changes before exiting.",
                "default": False
            }
        },
        "additionalProperties": False
    }
    
    async def execute(
        self,
        force: bool = False,
        stashChanges: bool = False
    ) -> ExitWorktreeResponse:
        """Execute the worktree exit operation."""
        pass

6.2.2 Response Schema

class ExitWorktreeResponse(ToolResult):
    success: bool
    mainWorktree: WorktreeInfo
    previousWorktree: WorktreeInfo | None = None
    message: str
    stashResult: str | None = None  # "stashed" or None

6.2.3 Execution Flow

1. Determine if currently in worktree vs main
   └─> Get .git file path

2. If already in main worktree:
   └─> Return success (idempotent)

3. Get main worktree path from .git file

4. Validate main worktree is accessible
   └─> MAIN_WORKTREE_UNAVAILABLE if fails

5. Check for uncommitted changes
   └─> If force == False and stashChanges == False:
       └─> Return UNCOMMITTED_CHANGES error
   └─> If stashChanges == True:
       └─> Execute: git stash
       └─> Store stash reference

6. Update session context:
   └─> Store previous worktree info
   └─> Set new CWD to main worktree path
   └─> Clear worktree-specific context

7. Return ExitWorktreeResponse

6.3 ListWorktreesTool

6.3.1 Interface Definition

class ListWorktreesTool(BaseTool):
    """Tool for listing all worktrees in a repository."""
    
    name: str = "ListWorktreesTool"
    description: str = "List all Git worktrees in the current repository."
    version: str = "1.0.0"
    
    parameters: dict = {
        "type": "object",
        "properties": {
            "verbose": {
                "type": "boolean",
                "description": "Include detailed information (HEAD, branch details).",
                "default": False
            },
            "includePrunable": {
                "type": "boolean",
                "description": "Include prunable (orphan) worktrees.",
                "default": False
            }
        },
        "additionalProperties": False
    }
    
    async def execute(
        self,
        verbose: bool = False,
        includePrunable: bool = False
    ) -> ListWorktreesResponse:
        """Execute the worktree listing operation."""
        pass

6.3.2 Response Schema

class ListWorktreesResponse(ToolResult):
    success: bool
    worktrees: list[WorktreeInfo]
    count: int
    message: str

Security Requirements

12.1 Branch Protection

12.1.1 Default Protected Branches

The following branches are protected by default and cannot have worktrees created on them:

• main
• master
• develop
• HEAD

12.1.2 Configuration

Protected branches can be configured via:

{
  "git": {
    "worktree": {
      "protectedBranches": [
        "main",
        "master",
        "release/*",
        "hotfix/*"
      ]
    }
  }
}

12.1.3 Pattern Matching

Branch protection supports glob patterns:

• * matches any sequence of characters
• ? matches exactly one character
• [abc] matches character class

12.2 Conflict Handling

12.2.1 Worktree Branch Conflicts

If a branch already has a worktree, the tool must:

1. Reject the creation request
2. Return the existing worktree path
3. Suggest entering the existing worktree

12.2.2 Path Conflicts

If the target path already exists:

1. Check if it's a valid worktree
2. If valid worktree: return existing info
3. If not valid worktree: reject unless force=true
4. If force=true: warn user, then proceed

12.2.3 Uncommitted Changes

When exiting a worktree with changes:

1. Default: reject exit
2. With stashChanges=true: auto-stash
3. With force=true: allow exit, changes remain

12.3 Path Validation

12.3.1 Repository Bounds

Worktrees must be created within the repository structure:

• Allowed: <repo>/worktrees/*, <repo>/features/*, <repo>/../branch-name
• Not Allowed: /tmp/*, /home/*, absolute paths outside repo

12.3.2 Path Sanitization

All paths must be sanitized:

• Remove null bytes
• Normalize .. and . components
• Reject paths with symbolic links outside repo (with warning)
• Limit path length to 4096 characters

12.4 Audit Logging

All worktree operations must be logged:

{
  "timestamp": "2026-04-08T12:00:00Z",
  "event": "WORKTREE_CREATE",
  "user": "agent-001",
  "branch": "feature/auth",
  "path": "/project/worktrees/feature-auth",
  "success": true,
  "protectedBranchAttempt": false
}

Testing Requirements

Test Coverage Requirements

Functional Testing Requirements

Security Testing Requirements

Performance Testing Requirements

Test Environment Requirements

Test Execution Requirements

• All unit tests must pass before merge
• All integration tests must pass before release
• Security tests must pass 100% before deployment
• Performance tests must meet thresholds

Testing

8.1 Unit Tests

8.1.1 EnterWorktreeTool Tests

8.1.2 ExitWorktreeTool Tests

8.1.3 ListWorktreesTool Tests

8.2 Integration Tests

8.3 End-to-End Tests

8.4 Test Environment Requirements

@pytest.fixture
def git_repo(tmp_path):
    """Create a test git repository."""
    repo = tmp_path / "test_repo"
    repo.mkdir()
    subprocess.run(["git", "init"], cwd=repo, check=True)
    Path(repo / ".gitkeep").touch()
    subprocess.run(["git", "add", "."], cwd=repo, check=True)
    subprocess.run(["git", "commit", "-m", "Initial commit"], cwd=repo, check=True)
    return repo

@pytest.fixture
def worktree_dir(tmp_path):
    """Create a worktree directory."""
    wt = tmp_path / "worktrees" / "test"
    wt.mkdir(parents=True)
    return wt

Dependencies

9.1 Runtime Dependencies

9.2 Internal Dependencies

9.3 External Dependencies

Governance

15.1 Policy Enforcement

• Worktree creation requires project:write permission
• Branch protection enforced via PAM++ policies
• Protected branch attempts logged for security auditing

15.2 Audit Logging

All worktree operations must be logged:

async def log_worktree_action(action: str, details: dict):
    await audit_log({
        "event_type": "worktree",
        "action": action,
        "details": details,
        "timestamp": datetime.utcnow().isoformat()
    })

15.3 Compliance

• Worktrees cannot bypass branch protection policies
• All operations must comply with repository governance rules
• Security events logged for compliance reporting

Integration Points

16.1 Git Operations

16.2 Session Management

16.3 Configuration

Success Criteria

17.1 Functional Success Criteria

17.2 Error Handling Success Criteria

17.3 Performance Success Criteria

17.4 Security Success Criteria

Unit Tests

class TestEnterWorktreeTool:
    async def test_enter_existing_worktree(self):
        tool = EnterWorktreeTool()
        result = await tool.execute(path="/path/to/worktree")
        assert result.success == True
        assert result.branch == "feature-branch"
    
    async def test_enter_nonexistent_worktree(self):
        tool = EnterWorktreeTool()
        result = await tool.execute(path="/nonexistent")
        assert result.success == False
        assert "not found" in result.error

Integration Tests

• Git worktree operations
• Branch protection rules
• Session state management

Test Coverage

• Unit: >80%
• Integration: 100%

Governance (PAM++)

Policy Enforcement

• Worktree creation requires project:write
• Branch protection enforced via PAM++
• Protected branches logged

Audit Logging

async def log_worktree_action(action: str, details: dict):
    await audit_log({
        "event_type": "worktree",
        "action": action,
        "details": details
    })

Observability

Logging Requirements

1. Component Logging
   • Log all major operations with appropriate log levels
   • Include correlation IDs for request tracing
   • Log performance metrics for critical operations
   • Log errors with full context for debugging

Metrics Requirements

1. Performance Metrics
   • Operation duration histograms
   • Request/error rate counters
   • Resource utilization gauges
   • Business metrics relevant to domain

Tracing Requirements

1. Distributed Tracing
   • Trace propagation across component boundaries
   • Span attributes for domain-specific context
   • Trace sampling based on operational needs

Alerting Requirements

1. Critical Alerts
   • Error rate spikes
   • Performance degradation
   • Resource exhaustion
   • Business metric anomalies

Dashboard Requirements

1. Operational Dashboard
   • Real-time system health
   • Performance trends
   • Error analysis
   • Resource monitoring

Revision History

References

• Git Worktree Documentation
• Git Internals - Repository Format
• Orchestrata Architecture Overview
• Error Handling Standard

End of SPEC-064

Related

• RTM page for 064-git-worktree-tools
• All specs
• RTM overview
• Gates