cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

docs(spec): describe git worktree sandbox path via temp dir placeholder
CI / benchmark-publish (pull_request) Has been skipped
Details
CI / lint (pull_request) Successful in 20s
Details
CI / push-validation (pull_request) Successful in 19s
Details
CI / helm (pull_request) Successful in 22s
Details
CI / quality (pull_request) Successful in 32s
Details
CI / build (pull_request) Successful in 32s
Details
CI / typecheck (pull_request) Successful in 49s
Details
CI / security (pull_request) Successful in 1m0s
Details
CI / e2e_tests (pull_request) Successful in 3m6s
Details
CI / integration_tests (pull_request) Successful in 4m0s
Details
CI / unit_tests (pull_request) Successful in 4m57s
Details
CI / docker (pull_request) Successful in 21s
Details
CI / coverage (pull_request) Successful in 10m18s
Details
CI / status-check (pull_request) Successful in 1s
Details
CI / benchmark-regression (pull_request) Successful in 58m0s
Details

Browse Source 
The GitWorktreeSandbox implementation (PR #5998) creates worktrees in the
system temp directory using tempfile.mkdtemp() with the prefix
ca-sandbox-<plan_id>-, producing OS-specific paths (e.g.,
&lt;SYSTEM_TEMP_DIR&gt;/ca-sandbox-<PLAN_ULID>-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
  <SYSTEM_TEMP_DIR> 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
This commit is contained in:
HAL 9000
2026-04-09 20:58:32 +00:00
parent fc9c730670
commit dd94c6c19f
2 changed files with 28 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+3
View File
@@ -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 `<SYSTEM_TEMP_DIR>/ca-sandbox-<PLAN_ULID>-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: <interval> (Next report expected: <ts>)`
declarations, enabling precise staleness detection.
docs/specification.md
+25 -21
View File
@@ -12947,12 +12947,12 @@ Start or resume execution for a plan.
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
╰──────────────────────────────────╯
╭─ Sandbox ──────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> /repos/api/.worktrees/plan-01HXM8 │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXM8C2 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
╰────────────────────────────────────────────╯
╭─ Sandbox ──────────────────────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> &lt;SYSTEM_TEMP_DIR&gt;/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-XXXXXX │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXM8C2 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
╰────────────────────────────────────────────────────────────────────╯
╭─ Strategy Summary ─────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Decisions:</span> 8 │
@@ -12987,7 +12987,7 @@ Start or resume execution for a plan.
Sandbox
Strategy: git_worktree
Path: /repos/api/.worktrees/plan-01HXM8
Path: <SYSTEM_TEMP_DIR>/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": "<SYSTEM_TEMP_DIR>/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: "<SYSTEM_TEMP_DIR>/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-<plan_id>-`. This produces paths of the form `<SYSTEM_TEMP_DIR>/ca-sandbox-<PLAN_ULID>-<RANDOM>/`. 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-<PLAN_ULID_PREFIX>`.
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
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
╰─────────────────────────────────────────╯
╭─ Sandbox ───────────────────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> /home/dev/projects/api-service/.worktrees/plan-01HXR1C1 │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXR1C1D2 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
╰─────────────────────────────────────────────────────────────────╯
╭─ Sandbox ──────────────────────────────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> &lt;SYSTEM_TEMP_DIR&gt;/ca-sandbox-01HXR1C1D2E3F4G5H6I7J8K9L0-XXXXXX │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXR1C1D2 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Strategy Summary ────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Decisions:</span> 4 │
@@ -36758,12 +36762,12 @@ The strategy actor has read the codebase, identified the relevant files, and pro
│ <span style="color: #5599ff; font-weight: 600;">Attempt:</span> 1 │
╰─────────────────────────────────────────╯
╭─ Sandbox ───────────────────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> /home/dev/projects/api-service/.worktrees/plan-01HXR1C1 │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXR1C1D2 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
╰─────────────────────────────────────────────────────────────────╯
╭─ Sandbox ──────────────────────────────────────────────────────────────────╮
│ <span style="color: #5599ff; font-weight: 600;">Strategy:</span> git_worktree │
│ <span style="color: #5599ff; font-weight: 600;">Path:</span> &lt;SYSTEM_TEMP_DIR&gt;/ca-sandbox-01HXR1C1D2E3F4G5H6I7J8K9L0-XXXXXX │
│ <span style="color: #5599ff; font-weight: 600;">Branch:</span> cleveragents/plan-01HXR1C1D2 │
│ <span style="color: #66cc66; font-weight: 600;">Status:</span> active │
╰────────────────────────────────────────────────────────────────────────────╯
╭─ Progress ────────────────────────────────╮
│ <span style="color: #66cc66; font-weight: 600;">✓</span> Collect context (0.4s) │