# v3.0.0 — Deep Dive: Sandbox, Persistence & Domain Model

Internal architecture details for CleverAgents v3.0.0.

---

## Git Worktree Sandbox

The git worktree sandbox isolates LLM-generated changes in a dedicated branch
and worktree until the user approves them via `agents plan apply`.

See the full [Git Worktree Sandbox](../../modules/git-worktree-sandbox.md) module docs.

### How It Works

1. Plan execute creates branch `cleveragents/plan-<id>` from current HEAD.
2. A temporary git worktree is created in a system temp directory.
3. The LLM writes changes only inside the worktree (not the real repo).
4. `plan diff` shows proposed changes as unified diff.
5. `plan apply` merges sandbox into original via `git merge`, then cleans up.
6. `plan cancel` discards the worktree — no real repo changes.

Non-git resources (e.g. `fs-directory`) fall back to `shutil.copy2`.

### Apply Summary Output

```
╭─ Apply Summary ────────────────────────────────────────╮
│ Plan ID:    plan-01HZ...                              │
│ Artifacts:  3 files changed                           │
│ Insertions: +142                                      │
│ Deletions:  -17                                       │
╰───────────────────────────────────────────────────────╯
╭─ Sandbox Cleanup ──────────────────────────────────────╮
│ [x] Worktree removed                                 │
│ [x] Branch deleted                                   │
╰───────────────────────────────────────────────────────╯
```

---

## SQLite Persistence with Alembic

All entities persist in `~/.cleveragents/cleveragents.db`.

### Managed Tables

| Table | Description |
|-------|-------------|
| `actions` | Action templates |
| `action_arguments`, `action_invariants` | Per-action metadata |
| `resources` | Resource instances |
| `projects`, `project_resource_links` | Projects and links |
| `plans`, `plan_project_links` | Plans and project bindings |
| `decisions` | Decision tree nodes per plan |

### Migration Commands

```bash
alembic upgrade head    # apply pending migrations
alembic current         # show current revision
alembic history         # migration history
```

---

## Domain Model (Pydantic v2)

All domain entities use Pydantic v2 with `frozen=True` for immutability.

```python
from cleveragents.domain.models import Action, Resource, Project, Plan

action = Action(
    name="local/code-coverage",
    description="Increase code coverage",
    strategy_actor="openai/gpt-4",
    execution_actor="openai/gpt-4",
    definition_of_done="Coverage reaches target.",
)
# action.name = "other"  # raises ValidationError (frozen)
```

ULIDs (Universally Unique Lexicographically Sortable Identifiers) are the primary keys.

See [ADR-019](../../adr/ADR-019-storage-and-persistence.md) for storage details.

---

## See Also

- [CLI Reference](cli-reference.md) — All command documentation
- [Git Worktree Sandbox](../../modules/git-worktree-sandbox.md)
- [ADR-006](../../adr/ADR-006-plan-lifecycle.md): Plan Lifecycle
- [ADR-019](../../adr/ADR-019-storage-and-persistence.md): Storage & Persistence
