Proposal: update specification — document GitWorktreeSandbox implementation and merge-based apply #6192

New issue

Open

opened 2026-04-09 17:32:01 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-09 17:32:01 +00:00

Owner

Proposal: Update Specification — Git Worktree Sandbox and Merge-Based Apply

What Changed in the Implementation

Merged PR #5998 (feat(plan): implement git worktree sandbox for execute and merge-based apply, merged 2026-04-09) introduced a concrete GitWorktreeSandbox class in src/cleveragents/infrastructure/sandbox/git_worktree.py. This is a significant implementation of the sandbox model that the spec describes abstractly.

What Spec Sections Need Updating

§19237 — Execution Workspace / Sandbox Model (Detailed)

Current text (§19253 — Sandbox Implementation Strategies): Describes sandbox strategies generically (copy-on-write, overlay filesystem, git worktree) without specifying which is the primary implementation for git-checkout resources.

Proposed addition: Add a subsection documenting the GitWorktreeSandbox as the canonical sandbox strategy for git-checkout resources:

##### GitWorktreeSandbox (Primary Strategy for git-checkout Resources)

For resources of type `git-checkout`, the system uses `GitWorktreeSandbox`:

- **Branch naming**: `cleveragents/plan-<sanitised-plan-id>` (hyphens replace non-alphanumeric chars)
- **Worktree path**: temporary directory created via `tempfile.mkdtemp(prefix="ca-sandbox-<plan-id>-")`
- **Execute phase**: LLM writes files to the worktree; changes are committed on the sandbox branch
- **Apply phase**: sandbox branch is merged into the original branch via `git merge <branch> --no-edit`
- **Rollback from ACTIVE**: `git reset --hard <base_commit>` + `git clean -fd` in the worktree
- **Rollback from COMMITTED**: additionally `git reset --hard <pre_merge_commit>` on the original branch
- **Cleanup**: `git worktree remove --force` + `git branch -D <branch>` + `git worktree prune`
- **Non-git fallback**: projects without a `git-checkout` resource fall back to flat directory copy (`shutil.copy2`)

The `SandboxStatus` lifecycle is: `PENDING → CREATED → ACTIVE → COMMITTED → CLEANED_UP` (or `ROLLED_BACK` from ACTIVE/COMMITTED, or `ERRORED` on failure).

§19380 — `sandbox_ref` field in Execution Data Model

Proposed addition: Document that sandbox_ref.metadata includes strategy, branch, original_branch, base_commit, and worktree_path keys when using GitWorktreeSandbox.

§19843 — Apply Phase: What Apply Does

Current text: Describes apply as copying artifacts from sandbox to project.

Proposed update: Clarify that for git-checkout resources, apply is implemented as a git merge of the sandbox branch into the original branch, producing a proper git history entry. The spec panels printed are:

Apply Summary: Plan ID, artifacts count, insertions/deletions, project name, applied-at timestamp
Sandbox Cleanup: worktree removed, branch merged to main
Next Steps: review git diff, commit changes
Footer: ✓ OK Changes applied

Rationale

The implementation in PR #5998 is a better design than the spec's abstract description — it uses git's native isolation mechanism (worktrees) rather than filesystem copies, preserving full git history and enabling proper conflict detection during apply. The spec should document this concrete, superior approach as the canonical implementation for git-checkout resources.

Scope

Spec sections affected:

§19237 — Execution Workspace / Sandbox Model (Detailed)
§19253 — Sandbox Implementation Strategies (add GitWorktreeSandbox subsection)
§19380 — sandbox_ref field
§19843 — Apply Phase: What Apply Does
§19858 — Apply Responsibilities (update to mention git merge)

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

## Proposal: Update Specification — Git Worktree Sandbox and Merge-Based Apply ### What Changed in the Implementation **Merged PR #5998** (`feat(plan): implement git worktree sandbox for execute and merge-based apply`, merged 2026-04-09) introduced a concrete `GitWorktreeSandbox` class in `src/cleveragents/infrastructure/sandbox/git_worktree.py`. This is a significant implementation of the sandbox model that the spec describes abstractly. ### What Spec Sections Need Updating #### §19237 — Execution Workspace / Sandbox Model (Detailed) **Current text** (§19253 — Sandbox Implementation Strategies): Describes sandbox strategies generically (copy-on-write, overlay filesystem, git worktree) without specifying which is the primary implementation for git-checkout resources. **Proposed addition**: Add a subsection documenting the `GitWorktreeSandbox` as the canonical sandbox strategy for `git-checkout` resources: ```markdown ##### GitWorktreeSandbox (Primary Strategy for git-checkout Resources) For resources of type `git-checkout`, the system uses `GitWorktreeSandbox`: - **Branch naming**: `cleveragents/plan-<sanitised-plan-id>` (hyphens replace non-alphanumeric chars) - **Worktree path**: temporary directory created via `tempfile.mkdtemp(prefix="ca-sandbox-<plan-id>-")` - **Execute phase**: LLM writes files to the worktree; changes are committed on the sandbox branch - **Apply phase**: sandbox branch is merged into the original branch via `git merge <branch> --no-edit` - **Rollback from ACTIVE**: `git reset --hard <base_commit>` + `git clean -fd` in the worktree - **Rollback from COMMITTED**: additionally `git reset --hard <pre_merge_commit>` on the original branch - **Cleanup**: `git worktree remove --force` + `git branch -D <branch>` + `git worktree prune` - **Non-git fallback**: projects without a `git-checkout` resource fall back to flat directory copy (`shutil.copy2`) The `SandboxStatus` lifecycle is: `PENDING → CREATED → ACTIVE → COMMITTED → CLEANED_UP` (or `ROLLED_BACK` from ACTIVE/COMMITTED, or `ERRORED` on failure). ``` #### §19380 — `sandbox_ref` field in Execution Data Model **Proposed addition**: Document that `sandbox_ref.metadata` includes `strategy`, `branch`, `original_branch`, `base_commit`, and `worktree_path` keys when using `GitWorktreeSandbox`. #### §19843 — Apply Phase: What Apply Does **Current text**: Describes apply as copying artifacts from sandbox to project. **Proposed update**: Clarify that for git-checkout resources, apply is implemented as a `git merge` of the sandbox branch into the original branch, producing a proper git history entry. The spec panels printed are: - **Apply Summary**: Plan ID, artifacts count, insertions/deletions, project name, applied-at timestamp - **Sandbox Cleanup**: worktree removed, branch merged to main - **Next Steps**: review git diff, commit changes - **Footer**: `✓ OK Changes applied` ### Rationale The implementation in PR #5998 is a **better design than the spec's abstract description** — it uses git's native isolation mechanism (worktrees) rather than filesystem copies, preserving full git history and enabling proper conflict detection during apply. The spec should document this concrete, superior approach as the canonical implementation for git-checkout resources. ### Scope Spec sections affected: - §19237 — Execution Workspace / Sandbox Model (Detailed) - §19253 — Sandbox Implementation Strategies (add GitWorktreeSandbox subsection) - §19380 — `sandbox_ref` field - §19843 — Apply Phase: What Apply Does - §19858 — Apply Responsibilities (update to mention git merge) --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater

HAL9000 added the

labels

2026-04-09 17:33:21 +00:00

HAL9000 added this to the v3.4.0 milestone

2026-04-09 17:33:46 +00:00