Workspace Isolation

​

How It Works

your-repo/
├── .draft/
│   └── worktrees/
│       ├── ticket-abc/     # Isolated copy for ticket ABC
│       │   ├── src/
│       │   ├── tests/
│       │   └── .draft/
│       │       └── logs/
│       │           └── job-123.log
│       └── ticket-def/     # Isolated copy for ticket DEF
│           ├── src/
│           └── ...
├── src/                    # Your main working tree (untouched)
└── ...

​

Lifecycle

1. Creation — When a job runs, a worktree is created at .draft/worktrees/{ticket_id}/
2. Branching — Each worktree gets a dedicated branch: goal/{goal_id}/ticket/{ticket_id}
3. Execution — AI agent and verification commands run inside the worktree
4. Logging — Job logs are written to {worktree}/.draft/logs/{job_id}.log
5. Cleanup — When a ticket reaches DONE or ABANDONED, its worktree is automatically removed

​

Safety Guarantees

• Your main branch is never modified during execution
• Each ticket’s changes are isolated to its own branch
• The WorktreeValidator ensures no operations run on protected branches (main, master, develop)
• Board’s repo_root is always authoritative — client-provided paths are rejected

​

Configuration

# backend/.env

# Path to the git repository (default: project root)
GIT_REPO_PATH=/path/to/your/repo

# Base branch for worktree creation (default: main, fallback: master)
BASE_BRANCH=main

​

Requirements

• The project must be a git repository
• The configured base branch must exist
• If the directory is not a git repository, jobs run without isolation (with a warning)

​

Cleanup

• A ticket reaches a terminal state (DONE or ABANDONED)
• The configured TTL expires (default: 72 hours)
• You manually trigger cleanup via the maintenance API

# Manual cleanup of stale worktrees
curl -X POST http://localhost:8000/maintenance/cleanup-worktrees