131 lines
4.2 KiB
Markdown
131 lines
4.2 KiB
Markdown
# Workspace Source-Of-Truth Cleanup Plan
|
|
|
|
## Scope
|
|
|
|
Only this worktree:
|
|
`/Users/moboudra/.paseo/worktrees/1luy0po7/workspace-sot-hard-cut`
|
|
|
|
## Objectives
|
|
|
|
1. One server-owned source of truth for workspace identity.
|
|
2. Header and sidebar render the same workspace name field.
|
|
3. Remove client-side workspace construction from agent data.
|
|
4. Hard cut legacy paths (no dual-read compatibility layer).
|
|
|
|
## Non-Objectives
|
|
|
|
1. No UI-only taxonomy in canonical model (`subtitle`, `titleKind`).
|
|
2. No React derivation from branch/path basename for workspace naming.
|
|
3. No silent fallbacks masking missing state (`?? ""`, cwd fallback label).
|
|
|
|
## Phase 0: Audit Existing Worktree Changes
|
|
|
|
1. Inventory all modified files in this worktree.
|
|
2. For each hunk, classify as `keep`, `delete`, or `rewrite`.
|
|
3. Build a bad-pattern list and remove all of these:
|
|
- Workspace naming fallback in React.
|
|
- Canonical payload fields that are presentation-only.
|
|
- Any primary label logic equivalent to `Unknown branch`.
|
|
- Any sidebar workspace list constructed from live agent rows.
|
|
|
|
### Acceptance
|
|
|
|
1. Full inventory exists before further refactor work.
|
|
2. Every bad pattern has a mapped removal location.
|
|
|
|
## Phase 1: Canonical Model Simplification
|
|
|
|
Define a minimal server canonical workspace entity:
|
|
|
|
- `id`: normalized cwd (single identity field)
|
|
- `projectId`: stable grouping key
|
|
- `name`: canonical workspace name (server computed)
|
|
- `status`: dominant state bucket
|
|
- `activityAt`: nullable ISO timestamp
|
|
|
|
Do not include UI/presentation fields in canonical payload.
|
|
|
|
### Acceptance
|
|
|
|
1. No duplicate identity fields (`workspaceId` + `cwd`) in canonical contract.
|
|
2. No subtitle/title-kind fields in canonical contract.
|
|
|
|
## Phase 2: Server Aggregation and RPC
|
|
|
|
1. Build workspace aggregation in `session.ts` from authoritative server state.
|
|
2. Compute workspace `name` once in server policy code.
|
|
3. Provide:
|
|
- `fetch_workspaces_request/response` snapshot RPC
|
|
- `workspace_update` incremental upsert/remove stream
|
|
4. Keep update semantics aligned with existing directory subscription behavior.
|
|
|
|
### Acceptance
|
|
|
|
1. Non-git and git workspaces both resolve deterministic `name`.
|
|
2. No `Unknown branch` emitted by server.
|
|
3. Workspace update stream reflects agent lifecycle/state changes.
|
|
|
|
## Phase 3: Client Store Wiring
|
|
|
|
1. Add workspace map in session store keyed by canonical `id`.
|
|
2. Hydrate only from `fetch_workspaces`.
|
|
3. Apply only `workspace_update` events for incremental updates.
|
|
4. Keep workspace state channel separate from agent-list derivation.
|
|
|
|
### Acceptance
|
|
|
|
1. Workspace map is populated strictly from workspace RPCs.
|
|
2. No workspace assembly logic from agent lists in runtime/store.
|
|
|
|
## Phase 4: UI Hard Cut
|
|
|
|
1. Sidebar row label reads only `workspace.name`.
|
|
2. Header title reads only `workspace.name`.
|
|
3. Remove all local workspace naming helpers based on cwd/branch.
|
|
4. Missing descriptor after hydration must render explicit missing-state UI, not fallback text.
|
|
|
|
### Acceptance
|
|
|
|
1. Header and sidebar names are guaranteed identical source field.
|
|
2. No `?? ""`/cwd/branch fallback paths for workspace name.
|
|
|
|
## Phase 5: Legacy Deletion
|
|
|
|
1. Delete prior client sidebar workspace-building path(s).
|
|
2. Remove `Unknown branch` primary naming logic.
|
|
3. Remove any query/helper used only for old workspace naming.
|
|
4. Delete dead types/helpers from failed intermediate designs.
|
|
|
|
### Acceptance
|
|
|
|
1. No app code path builds workspace rows from agent lists.
|
|
2. Legacy naming/building code fully removed in same change set.
|
|
|
|
## Phase 6: Verification
|
|
|
|
1. Protocol/schema tests for workspace request/response/update.
|
|
2. Server aggregation tests:
|
|
- non-git workspace
|
|
- git branch workspace
|
|
- detached/headless workspace
|
|
- removal/update behavior
|
|
3. UI tests:
|
|
- selected workspace header name equals sidebar workspace name
|
|
- explicit missing-state rendering when descriptor absent post-hydration
|
|
4. Run `npm run typecheck`.
|
|
5. Manual validation in this worktree daemon+expo stack.
|
|
|
|
### Acceptance
|
|
|
|
1. Tests pass.
|
|
2. Typecheck passes.
|
|
3. Manual verification confirms name parity and status correctness.
|
|
|
|
## Execution Guardrails
|
|
|
|
1. Work only in `workspace-sot-hard-cut`.
|
|
2. No destructive git operations.
|
|
3. No fallback naming logic in React.
|
|
4. One naming policy and source of truth: server.
|
|
5. Hard cut means old code removed, not left dormant.
|