wip

foundry/packages/backend/CLAUDE.md

@@ -5,30 +5,29 @@
 Keep the backend actor tree aligned with this shape unless we explicitly decide to change it:
 
 ```text
-WorkspaceActor
-├─ HistoryActor(workspace-scoped global feed)
-├─ ProjectActor(repo)
-│  ├─ ProjectBranchSyncActor
-│  ├─ ProjectPrSyncActor
+OrganizationActor
+├─ HistoryActor(organization-scoped global feed)
+├─ GithubDataActor
+├─ RepositoryActor(repo)
 │  └─ TaskActor(task)
 │     ├─ TaskSessionActor(session) × N
 │     │  └─ SessionStatusSyncActor(session) × 0..1
 │     └─ Task-local workbench state
-└─ SandboxInstanceActor(providerId, sandboxId) × N
+└─ SandboxInstanceActor(sandboxProviderId, sandboxId) × N
 ```
 
 ## Ownership Rules
 
-- `WorkspaceActor` is the workspace coordinator and lookup/index owner.
-- `HistoryActor` is workspace-scoped. There is one workspace-level history feed.
-- `ProjectActor` is the repo coordinator and owns repo-local caches/indexes.
+- `OrganizationActor` is the organization coordinator and lookup/index owner.
+- `HistoryActor` is organization-scoped. There is one organization-level history feed.
+- `RepositoryActor` is the repo coordinator and owns repo-local caches/indexes.
 - `TaskActor` is one branch. Treat `1 task = 1 branch` once branch assignment is finalized.
 - `TaskActor` can have many sessions.
 - `TaskActor` can reference many sandbox instances historically, but should have only one active sandbox/session at a time.
 - Session unread state and draft prompts are backend-owned workbench state, not frontend-local state.
 - Branch rename is a real git operation, not just metadata.
 - `SandboxInstanceActor` stays separate from `TaskActor`; tasks/sessions reference it by identity.
-- Sync actors are polling workers only. They feed parent actors and should not become the source of truth.
+- The backend stores no local git state. No clones, no refs, no working trees, and no git-spice. Repository metadata comes from GitHub API data and webhook events. Any working-tree git operation runs inside a sandbox via `executeInSandbox()`.
 - When a backend request path must aggregate multiple independent actor calls or reads, prefer bounded parallelism over sequential fan-out when correctness permits. Do not serialize independent work by default.
 
 ## Maintenance