feat(plan): implement spec-aligned git worktree apply with merge, summary, and cleanup #4454

Closed
opened 2026-04-08 12:59:23 +00:00 by hamza.khyari · 4 comments
Member

Metadata

  • Commit Message: feat(plan): implement git worktree sandbox for execute and merge-based apply
  • Branch: feature/git-worktree-apply

Background

The specification (lines 12105, 13225-13280) defines the Apply phase as:

"Changeset is merged into real project resources"

The spec's apply output shows:

  • Apply Summary: artifacts count, insertions/deletions
  • Validation results from Execute phase
  • Sandbox Cleanup: worktree removed, branch merged to main, checkpoint archived

The current implementation (PR #4219) uses flat file copy from .cleveragents/sandbox/ to project root. This works end-to-end but diverges from the spec in several ways.

Spec vs Current Implementation

Spec Requirement Current Gap
Execute in git worktree sandbox Flat directory .cleveragents/sandbox/ No git worktree
Apply merges worktree branch to main shutil.copy2 file copy No git merge
Apply Summary panel (artifacts, insertions/deletions) "Applied N file(s)" message No detailed stats
Validation results display Not shown Validation framework not wired
Sandbox cleanup: worktree removed, branch merged shutil.rmtree of sandbox dir No git cleanup
Checkpoint archived after apply Not done Checkpoint not referenced

Prerequisites

  • GitCheckoutHandler.create_sandbox() exists (PR #1067, issue #836) but is not called by PlanExecutor
  • SandboxManager.get_or_create_sandbox() supports git_worktree strategy
  • CheckpointManager is wired into PlanExecutor (PR #4218, issue #1253)

Acceptance Criteria

  • Execute phase creates a git worktree for the plan (not a flat directory)
  • LLM file output is written to the worktree (committed on a branch)
  • Apply merges the worktree branch into the project's current branch
  • Apply Summary panel shows: files changed, insertions, deletions, project name
  • Validation results from Execute phase displayed during apply
  • Worktree removed after successful apply
  • Checkpoint archived after apply
  • Fallback to flat copy when project is not a git repository

Subtasks

  • Wire GitCheckoutHandler.create_sandbox() into PlanExecutor for git-checkout resources
  • Execute phase: commit LLM output to worktree branch
  • Apply phase: git merge worktree branch into main
  • Apply Summary panel with git diff --stat output
  • Display validation results from execute phase
  • Worktree cleanup after apply (git worktree remove)
  • Checkpoint archival after apply
  • Fallback to current flat copy for non-git projects
  • Tests (Behave): git worktree apply lifecycle
  • Tests (Robot): E2E git merge apply
  • Verify coverage >= 97%
  • Run nox (all default sessions)

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

Current Implementation Details (PR #4219)

The flat file copy implementation lives in these locations:

Execute phase (file writing)

  • src/cleveragents/cli/commands/plan.py_get_plan_executor() at line ~1394 sets sandbox_root=.cleveragents/sandbox/
  • src/cleveragents/application/services/llm_actors.py_write_to_sandbox() writes FILE: blocks to sandbox_root with path traversal guard

Apply phase (file copying)

  • src/cleveragents/cli/commands/plan.pylifecycle_apply_plan() at line ~2273 walks .cleveragents/sandbox/, copies to project root
  • Path traversal guards: os.path.normpath + startswith(project_root)
  • Protected dirs: .cleveragents, .git, .hg, .svn skipped
  • Per-file error handling: try/except OSError per shutil.copy2
  • Sandbox preserved on partial failure, cleaned on full success

Context hydration (dependency)

  • src/cleveragents/application/services/context_tier_hydrator.py — reads files from linked resources, must work regardless of sandbox strategy
  • LLMExecuteActor receives tier_service, project_repository, resource_registry via constructor injection

What to preserve as fallback

When the project is NOT a git repository (no .git/ directory), the flat copy path must remain active. The git worktree approach should be the default when a git-checkout resource is linked, with flat copy as the fallback for fs-directory and other non-git resource types.

## Metadata - **Commit Message**: `feat(plan): implement git worktree sandbox for execute and merge-based apply` - **Branch**: `feature/git-worktree-apply` ## Background The specification (lines 12105, 13225-13280) defines the Apply phase as: > "Changeset is merged into real project resources" The spec's apply output shows: - Apply Summary: artifacts count, insertions/deletions - Validation results from Execute phase - Sandbox Cleanup: worktree removed, branch merged to main, checkpoint archived The current implementation (PR #4219) uses flat file copy from `.cleveragents/sandbox/` to project root. This works end-to-end but diverges from the spec in several ways. ## Spec vs Current Implementation | Spec Requirement | Current | Gap | |---|---|---| | Execute in git worktree sandbox | Flat directory `.cleveragents/sandbox/` | No git worktree | | Apply merges worktree branch to main | `shutil.copy2` file copy | No git merge | | Apply Summary panel (artifacts, insertions/deletions) | "Applied N file(s)" message | No detailed stats | | Validation results display | Not shown | Validation framework not wired | | Sandbox cleanup: worktree removed, branch merged | `shutil.rmtree` of sandbox dir | No git cleanup | | Checkpoint archived after apply | Not done | Checkpoint not referenced | ## Prerequisites - `GitCheckoutHandler.create_sandbox()` exists (PR #1067, issue #836) but is not called by `PlanExecutor` - `SandboxManager.get_or_create_sandbox()` supports `git_worktree` strategy - `CheckpointManager` is wired into PlanExecutor (PR #4218, issue #1253) ## Acceptance Criteria - [ ] Execute phase creates a git worktree for the plan (not a flat directory) - [ ] LLM file output is written to the worktree (committed on a branch) - [ ] Apply merges the worktree branch into the project's current branch - [ ] Apply Summary panel shows: files changed, insertions, deletions, project name - [ ] Validation results from Execute phase displayed during apply - [ ] Worktree removed after successful apply - [ ] Checkpoint archived after apply - [ ] Fallback to flat copy when project is not a git repository ## Subtasks - [ ] Wire `GitCheckoutHandler.create_sandbox()` into `PlanExecutor` for git-checkout resources - [ ] Execute phase: commit LLM output to worktree branch - [ ] Apply phase: `git merge` worktree branch into main - [ ] Apply Summary panel with `git diff --stat` output - [ ] Display validation results from execute phase - [ ] Worktree cleanup after apply (`git worktree remove`) - [ ] Checkpoint archival after apply - [ ] Fallback to current flat copy for non-git projects - [ ] Tests (Behave): git worktree apply lifecycle - [ ] Tests (Robot): E2E git merge apply - [ ] Verify coverage >= 97% - [ ] Run `nox` (all default sessions) ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. ## Current Implementation Details (PR #4219) The flat file copy implementation lives in these locations: ### Execute phase (file writing) - `src/cleveragents/cli/commands/plan.py` — `_get_plan_executor()` at line ~1394 sets `sandbox_root=.cleveragents/sandbox/` - `src/cleveragents/application/services/llm_actors.py` — `_write_to_sandbox()` writes `FILE:` blocks to `sandbox_root` with path traversal guard ### Apply phase (file copying) - `src/cleveragents/cli/commands/plan.py` — `lifecycle_apply_plan()` at line ~2273 walks `.cleveragents/sandbox/`, copies to project root - Path traversal guards: `os.path.normpath` + `startswith(project_root)` - Protected dirs: `.cleveragents`, `.git`, `.hg`, `.svn` skipped - Per-file error handling: `try/except OSError` per `shutil.copy2` - Sandbox preserved on partial failure, cleaned on full success ### Context hydration (dependency) - `src/cleveragents/application/services/context_tier_hydrator.py` — reads files from linked resources, must work regardless of sandbox strategy - `LLMExecuteActor` receives `tier_service`, `project_repository`, `resource_registry` via constructor injection ### What to preserve as fallback When the project is NOT a git repository (no `.git/` directory), the flat copy path must remain active. The git worktree approach should be the default when a `git-checkout` resource is linked, with flat copy as the fallback for `fs-directory` and other non-git resource types.
Owner

Thank you for filing this issue. I'm reviewing it now and will provide triage feedback shortly.


Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: human-liaison

Thank you for filing this issue. I'm reviewing it now and will provide triage feedback shortly. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: human-liaison
Owner

Issue reviewed and triaged.

This issue is well-formed: it has clear background with spec references, a gap analysis table comparing spec vs. current implementation, acceptance criteria, complete metadata (commit message + branch), subtasks, and a Definition of Done.

Context note: This issue builds on top of PR #4219 (issue #4222 — Apply phase file copy fix). It represents the next step toward full spec alignment for the Apply phase, moving from flat file copy to git worktree-based apply with merge semantics.

  • Priority: Medium — the current flat-copy implementation (PR #4219) is functional; this issue upgrades it to full spec compliance with git merge semantics. Important for correctness but not blocking basic usage.
  • Story Points: 8 (XL) — significant scope: git worktree wiring, commit-on-branch during execute, merge-based apply, Apply Summary panel, validation display, cleanup, checkpoint archival, fallback, and full test coverage.
  • Dependency: Depends on PR #4219 (issue #4222) being merged first, as this issue extends that work.
  • Next step: This issue is now verified and ready for implementation, pending merge of #4219.

Transitioning to State/Verified.


Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: human-liaison

Issue reviewed and triaged. This issue is well-formed: it has clear background with spec references, a gap analysis table comparing spec vs. current implementation, acceptance criteria, complete metadata (commit message + branch), subtasks, and a Definition of Done. **Context note:** This issue builds on top of PR #4219 (issue #4222 — Apply phase file copy fix). It represents the next step toward full spec alignment for the Apply phase, moving from flat file copy to git worktree-based apply with merge semantics. - **Priority**: Medium — the current flat-copy implementation (PR #4219) is functional; this issue upgrades it to full spec compliance with git merge semantics. Important for correctness but not blocking basic usage. - **Story Points**: 8 (XL) — significant scope: git worktree wiring, commit-on-branch during execute, merge-based apply, Apply Summary panel, validation display, cleanup, checkpoint archival, fallback, and full test coverage. - **Dependency**: Depends on PR #4219 (issue #4222) being merged first, as this issue extends that work. - **Next step**: This issue is now verified and ready for implementation, pending merge of #4219. Transitioning to `State/Verified`. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: human-liaison
Owner

MoSCoW classification: Should Have

Rationale: Implementing spec-aligned git worktree apply with merge, summary, and cleanup is an important feature for the plan apply workflow. The specification describes this behavior, and implementing it correctly improves the plan execution experience. Should Have — important but the system can function without it in the short term.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner

MoSCoW classification: **Should Have** Rationale: Implementing spec-aligned git worktree apply with merge, summary, and cleanup is an important feature for the plan apply workflow. The specification describes this behavior, and implementing it correctly improves the plan execution experience. Should Have — important but the system can function without it in the short term. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner
HAL9000 added this to the v3.5.0 milestone 2026-04-08 17:42:24 +00:00
hamza.khyari 2026-04-09 14:27:38 +00:00
Owner

State label reconciliation:

  • Previous state: State/In Review
  • Corrected to: State/Completed
  • Reason: Issue is closed but had incorrect/missing terminal state label. Work was completed via merged PR #5998.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

State label reconciliation: - Previous state: State/In Review - Corrected to: State/Completed - Reason: Issue is closed but had incorrect/missing terminal state label. Work was completed via merged PR #5998. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#4454
No description provided.