Proposal: update specification — correct git worktree sandbox path format to use system temp directory #6343

New issue

Closed

opened 2026-04-09 20:12:19 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-09 20:12:19 +00:00

Owner

Specification Update Proposal

Triggered by: Merged PR #5998 (feat(plan): implement git worktree sandbox for execute and merge-based apply)

What Changed in the Implementation

PR #5998 implemented GitWorktreeSandbox in src/cleveragents/infrastructure/sandbox/git_worktree.py. The implementation creates the worktree in a system temp directory using:

self._worktree_path = tempfile.mkdtemp(prefix=f"ca-sandbox-{safe_plan_id}-")

This produces paths like: /tmp/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-XXXXXX/

What Spec Section(s) Need Updating

Current spec state (lines 12950-12955, 12988-12992):

Sandbox
  Strategy: git_worktree
  Path: /repos/api/.worktrees/plan-01HXM8
  Branch: cleveragents/plan-01HXM8C2
  Status: active

The spec shows the worktree path as a .worktrees/ subdirectory inside the repository (e.g., /repos/api/.worktrees/plan-01HXM8).

Proposed change: Update the example path to reflect the actual implementation — a system temp directory with the ca-sandbox-<plan_id>- prefix:

Sandbox
  Strategy: git_worktree
  Path: /tmp/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-XXXXXX
  Branch: cleveragents/plan-01HXM8C2
  Status: active

Also update the JSON and YAML output examples at lines 13021-13060 accordingly.

Rationale

The implementation uses tempfile.mkdtemp() rather than a .worktrees/ subdirectory for good reasons:

Cleaner repo: Avoids polluting the repository directory with worktree subdirectories
OS-managed cleanup: System temp directories are cleaned up by the OS on reboot
No path conflicts: Temp dirs are guaranteed unique by the OS
Simpler implementation: No need to create/manage a .worktrees/ directory inside the repo

This is a genuine improvement over the spec's original design. The spec should be updated to match.

Scope

Section: §agents plan execute output examples (~lines 12940-13070)
Change type: Correction (update example path format)
Size: ~5-10 lines changed across Rich/Plain/JSON/YAML output examples
Impact: No architectural change — only the example path format changes

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: spec-updater

## Specification Update Proposal **Triggered by**: Merged PR #5998 (`feat(plan): implement git worktree sandbox for execute and merge-based apply`) --- ## What Changed in the Implementation PR #5998 implemented `GitWorktreeSandbox` in `src/cleveragents/infrastructure/sandbox/git_worktree.py`. The implementation creates the worktree in a **system temp directory** using: ```python self._worktree_path = tempfile.mkdtemp(prefix=f"ca-sandbox-{safe_plan_id}-") ``` This produces paths like: `/tmp/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-XXXXXX/` --- ## What Spec Section(s) Need Updating **Current spec state** (lines 12950-12955, 12988-12992): ``` Sandbox Strategy: git_worktree Path: /repos/api/.worktrees/plan-01HXM8 Branch: cleveragents/plan-01HXM8C2 Status: active ``` The spec shows the worktree path as a `.worktrees/` subdirectory inside the repository (e.g., `/repos/api/.worktrees/plan-01HXM8`). **Proposed change**: Update the example path to reflect the actual implementation — a system temp directory with the `ca-sandbox-<plan_id>-` prefix: ``` Sandbox Strategy: git_worktree Path: /tmp/ca-sandbox-01HXM8C2ZK4Q7C2B3F2R4VYV6J-XXXXXX Branch: cleveragents/plan-01HXM8C2 Status: active ``` Also update the JSON and YAML output examples at lines 13021-13060 accordingly. --- ## Rationale The implementation uses `tempfile.mkdtemp()` rather than a `.worktrees/` subdirectory for good reasons: 1. **Cleaner repo**: Avoids polluting the repository directory with worktree subdirectories 2. **OS-managed cleanup**: System temp directories are cleaned up by the OS on reboot 3. **No path conflicts**: Temp dirs are guaranteed unique by the OS 4. **Simpler implementation**: No need to create/manage a `.worktrees/` directory inside the repo This is a genuine improvement over the spec's original design. The spec should be updated to match. --- ## Scope - **Section**: `§agents plan execute` output examples (~lines 12940-13070) - **Change type**: Correction (update example path format) - **Size**: ~5-10 lines changed across Rich/Plain/JSON/YAML output examples - **Impact**: No architectural change — only the example path format changes --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater

Rows
Columns