From dd94c6c19f14f3df86c8d61daab94e0f879c62f1 Mon Sep 17 00:00:00 2001 From: CleverThis Date: Thu, 9 Apr 2026 20:58:32 +0000 Subject: [PATCH] docs(spec): describe git worktree sandbox path via temp dir placeholder The GitWorktreeSandbox implementation (PR #5998) creates worktrees in the system temp directory using tempfile.mkdtemp() with the prefix ca-sandbox--, producing OS-specific paths (e.g., <SYSTEM_TEMP_DIR>/ca-sandbox--XXXXXX/). The spec previously showed the worktree path as a .worktrees/ subdirectory inside the repository (e.g., /repos/api/.worktrees/plan-01HXM8). This was incorrect and inconsistent with the implementation. Changes: - Update all plan execute output examples (Rich/Plain/JSON/YAML) to use the prefix placeholder instead of hard-coding /tmp - Update the end-to-end workflow examples (strategize + execute panels) - Add explicit documentation of the git worktree path format in the Sandbox Implementation Strategies section, including rationale - Update the changelog to reference the cross-platform placeholder Triggered by: merged PR #5998 (GitWorktreeSandbox implementation) ISSUES CLOSED: #6343 --- CHANGELOG.md | 3 +++ docs/specification.md | 46 +++++++++++++++++++++++-------------------- 2 files changed, 28 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b26bc4871..734f4f2f8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -48,6 +48,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Changed +- **Specification** (#6343): Documented that git worktree sandboxes are created in + the system temporary directory (rendered as `/ca-sandbox--XXXXXX/`) + so example `plan execute` outputs stay platform-accurate instead of hard-coding `/tmp`. - **Automation Tracking Format**: All automation tracking issues now use a standardized header format with mandatory `Reporting Interval: (Next report expected: )` declarations, enabling precise staleness detection. diff --git a/docs/specification.md b/docs/specification.md index 4accaad8b..8e3054270 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -12947,12 +12947,12 @@ Start or resume execution for a plan. │ Attempt: 1 │ ╰──────────────────────────────────╯ - ╭─ Sandbox ──────────────────────────────────╮ - │ Strategy: git_worktree │ - │ Path: /repos/api/.worktrees/plan-01HXM8 │ - │ Branch: cleveragents/plan-01HXM8C2 │ - │ Status: active │ - ╰────────────────────────────────────────────╯ + ╭─ Sandbox ──────────────────────────────────────────────────────────╮ + │ Strategy: git_worktree │ + │ Path: <SYSTEM_TEMP_DIR>/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-XXXXXX │ + │ Branch: cleveragents/plan-01HXM8C2 │ + │ Status: active │ + ╰────────────────────────────────────────────────────────────────────╯ ╭─ Strategy Summary ─────────────────────╮ │ Decisions: 8 │ @@ -12987,7 +12987,7 @@ Start or resume execution for a plan. Sandbox Strategy: git_worktree - Path: /repos/api/.worktrees/plan-01HXM8 + Path: /ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-XXXXXX Branch: cleveragents/plan-01HXM8C2 Status: active @@ -13019,7 +13019,7 @@ Start or resume execution for a plan. "phase": "execute", "sandbox": { "strategy": "git_worktree", - "path": "/repos/api/.worktrees/plan-01HXM8", + "path": "/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-XXXXXX", "branch": "cleveragents/plan-01HXM8C2", "status": "active" }, @@ -13056,7 +13056,7 @@ Start or resume execution for a plan. phase: execute sandbox: strategy: git_worktree - path: "/repos/api/.worktrees/plan-01HXM8" + path: "/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-XXXXXX" branch: "cleveragents/plan-01HXM8C2" status: active worker: "local/executor" @@ -19272,6 +19272,10 @@ Different resource types require different sandbox strategies: Pros: natural rollback, diff support, efficient Cons: requires git +**Git worktree path format**: The worktree is created in the **system temp directory** (whatever `tempfile.gettempdir()` returns on the host OS) using `tempfile.mkdtemp()` with the prefix `ca-sandbox--`. This produces paths of the form `/ca-sandbox--/`. The worktree is **not** created inside the repository directory (e.g., not in `.worktrees/`). This avoids polluting the repository, leverages OS-managed cleanup on reboot, and guarantees path uniqueness. The branch name follows the pattern `cleveragents/plan-`. + +Example path (Linux): `/tmp/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-a3f7b2/` + **2. Filesystem copy sandbox** * Copy project directory to a sandbox directory @@ -36645,12 +36649,12 @@ Because the automation profile is `manual`, the plan stops and waits after creat │ Attempt: 1 │ ╰─────────────────────────────────────────╯ -╭─ Sandbox ───────────────────────────────────────────────────────╮ -│ Strategy: git_worktree │ -│ Path: /home/dev/projects/api-service/.worktrees/plan-01HXR1C1 │ -│ Branch: cleveragents/plan-01HXR1C1D2 │ -│ Status: active │ -╰─────────────────────────────────────────────────────────────────╯ +╭─ Sandbox ──────────────────────────────────────────────────────────────────╮ +│ Strategy: git_worktree │ +│ Path: <SYSTEM_TEMP_DIR>/ca-sandbox-01HXR1C1D2E3F4G5H6I7J8K9L0-XXXXXX │ +│ Branch: cleveragents/plan-01HXR1C1D2 │ +│ Status: active │ +╰────────────────────────────────────────────────────────────────────────────╯ ╭─ Strategy Summary ────────────────╮ │ Decisions: 4 │ @@ -36758,12 +36762,12 @@ The strategy actor has read the codebase, identified the relevant files, and pro │ Attempt: 1 │ ╰─────────────────────────────────────────╯ -╭─ Sandbox ───────────────────────────────────────────────────────╮ -│ Strategy: git_worktree │ -│ Path: /home/dev/projects/api-service/.worktrees/plan-01HXR1C1 │ -│ Branch: cleveragents/plan-01HXR1C1D2 │ -│ Status: active │ -╰─────────────────────────────────────────────────────────────────╯ +╭─ Sandbox ──────────────────────────────────────────────────────────────────╮ +│ Strategy: git_worktree │ +│ Path: <SYSTEM_TEMP_DIR>/ca-sandbox-01HXR1C1D2E3F4G5H6I7J8K9L0-XXXXXX │ +│ Branch: cleveragents/plan-01HXR1C1D2 │ +│ Status: active │ +╰────────────────────────────────────────────────────────────────────────────╯ ╭─ Progress ────────────────────────────────╮ │ ✓ Collect context (0.4s) │