paperclip/doc/plans/workspace-technical-implementation.md

Workspace Technical Implementation Spec

Role of This Document

This document translates workspace-product-model-and-work-product.md into an implementation-ready engineering plan.

It is intentionally concrete:

• schema and migration shape
• shared contract updates
• route and service changes
• UI changes
• rollout and compatibility rules

This is the implementation target for the first workspace-aware delivery slice.

Locked Decisions

These decisions are treated as settled for this implementation:

1. Add a new durable execution_workspaces table now.
2. Each issue has at most one current execution workspace at a time.
3. issues get explicit project_workspace_id and execution_workspace_id.
4. Workspace reuse is in scope for V1.
5. The feature is gated in the UI by /instance/settings > Experimental > Workspaces.
6. The gate is UI-only. Backend model changes and migrations always ship.
7. Existing users upgrade into compatibility-preserving defaults.
8. project_workspaces evolves in place rather than being replaced.
9. Work product is issue-first, with optional links to execution workspaces and runtime services.
10. GitHub is the only PR provider in the first slice.
11. Both adapter_managed and cloud_sandbox execution modes are in scope.
12. Workspace controls ship first inside existing project properties, not in a new global navigation area.
13. Subissues are out of scope for this implementation slice.

Non-Goals

• Building a full code review system
• Solving subissue UX in this slice
• Implementing reusable shared workspace definitions across projects in this slice
• Reworking all current runtime service behavior before introducing execution workspaces

Existing Baseline

The repo already has:

• project_workspaces
• projects.execution_workspace_policy
• issues.execution_workspace_settings
• runtime service persistence in workspace_runtime_services
• local git-worktree realization in workspace-runtime.ts

This implementation should build on that baseline rather than fork it.

Terminology

• Project workspace: durable configured codebase/root for a project
• Execution workspace: actual runtime workspace used for one or more issues
• Work product: user-facing output such as PR, preview, branch, commit, artifact, document
• Runtime service: process or service owned or tracked for a workspace
• Compatibility mode: existing behavior preserved for upgraded installs with no explicit workspace opt-in

Architecture Summary

The first slice should introduce three explicit layers:

1. Project workspace

   • existing durable project-scoped codebase record
   • extended to support local, git, non-git, and remote-managed shapes

2. Execution workspace

   • new durable runtime record
   • represents shared, isolated, operator-branch, or remote-managed execution context

3. Issue work product

   • new durable output record
   • stores PRs, previews, branches, commits, artifacts, and documents

The issue remains the planning and ownership unit. The execution workspace remains the runtime unit. The work product remains the deliverable/output unit.

Configuration and Deployment Topology

Important correction

This repo already uses PAPERCLIP_DEPLOYMENT_MODE for auth/deployment behavior (local_trusted | authenticated).

Do not overload that variable for workspace execution topology.

New env var

Add a separate execution-host hint:

• PAPERCLIP_EXECUTION_TOPOLOGY=local|cloud|hybrid

Default:

• if unset, treat as local

Purpose:

• influences defaults and validation for workspace configuration
• does not change current auth/deployment semantics
• does not break existing installs

Semantics

• local
  • Paperclip may create host-local worktrees, processes, and paths
• cloud
  • Paperclip should assume no durable host-local execution workspace management
  • adapter-managed and cloud-sandbox flows should be treated as first-class
• hybrid
  • both local and remote execution strategies may exist

This is a guardrail and defaulting aid, not a hard policy engine in the first slice.

Instance Settings

Add a new Experimental section under /instance/settings.

New setting

• experimental.workspaces: boolean

Rules:

• default false
• UI-only gate
• stored in instance config or instance settings API response
• backend routes and migrations remain available even when false

UI behavior when off

• hide workspace-specific issue controls
• hide workspace-specific project configuration
• hide issue Work Product tab if it would otherwise be empty
• do not remove or invalidate any stored workspace data

Data Model

1. Extend project_workspaces

Current table exists and should evolve in place.

New columns

• source_type text not null default 'local_path'
  • local_path | git_repo | non_git_path | remote_managed
• default_ref text null
• visibility text not null default 'default'
  • default | advanced
• setup_command text null
• cleanup_command text null
• remote_provider text null
  • examples: github, openai, anthropic, custom
• remote_workspace_ref text null
• shared_workspace_key text null
  • reserved for future cross-project shared workspace definitions

Backfill rules

• if existing row has repo_url, backfill source_type='git_repo'
• else if existing row has cwd, backfill source_type='local_path'
• else backfill source_type='remote_managed'
• copy existing repo_ref into default_ref

Indexes

• retain current indexes
• add (project_id, source_type)
• add (company_id, shared_workspace_key) non-unique for future support

2. Add execution_workspaces

Create a new durable table.

Columns

• id uuid pk
• company_id uuid not null
• project_id uuid not null
• project_workspace_id uuid null
• source_issue_id uuid null
• mode text not null
  • shared_workspace | isolated_workspace | operator_branch | adapter_managed | cloud_sandbox
• strategy_type text not null
  • project_primary | git_worktree | adapter_managed | cloud_sandbox
• name text not null
• status text not null default 'active'
  • active | idle | in_review | archived | cleanup_failed
• cwd text null
• repo_url text null
• base_ref text null
• branch_name text null
• provider_type text not null default 'local_fs'
  • local_fs | git_worktree | adapter_managed | cloud_sandbox
• provider_ref text null
• derived_from_execution_workspace_id uuid null
• last_used_at timestamptz not null default now()
• opened_at timestamptz not null default now()
• closed_at timestamptz null
• cleanup_eligible_at timestamptz null
• cleanup_reason text null
• metadata jsonb null
• created_at timestamptz not null default now()
• updated_at timestamptz not null default now()

Foreign keys

• company_id -> companies.id
• project_id -> projects.id
• project_workspace_id -> project_workspaces.id on delete set null
• source_issue_id -> issues.id on delete set null
• derived_from_execution_workspace_id -> execution_workspaces.id on delete set null

Indexes

• (company_id, project_id, status)
• (company_id, project_workspace_id, status)
• (company_id, source_issue_id)
• (company_id, last_used_at desc)
• (company_id, branch_name) non-unique

3. Extend issues

Add explicit workspace linkage.

New columns

• project_workspace_id uuid null
• execution_workspace_id uuid null
• execution_workspace_preference text null
  • inherit | shared_workspace | isolated_workspace | operator_branch | reuse_existing

Foreign keys

• project_workspace_id -> project_workspaces.id on delete set null
• execution_workspace_id -> execution_workspaces.id on delete set null

Backfill rules

• all existing issues get null values
• null should be interpreted as compatibility/inherit behavior

Invariants

• if project_workspace_id is set, it must belong to the issue's project and company
• if execution_workspace_id is set, it must belong to the issue's company
• if execution_workspace_id is set, the referenced workspace's project_id must match the issue's project_id

4. Add issue_work_products

Create a new durable table for outputs.

Columns

• id uuid pk
• company_id uuid not null
• project_id uuid null
• issue_id uuid not null
• execution_workspace_id uuid null
• runtime_service_id uuid null
• type text not null
  • preview_url | runtime_service | pull_request | branch | commit | artifact | document
• provider text not null
  • paperclip | github | vercel | s3 | custom
• external_id text null
• title text not null
• url text null
• status text not null
  • active | ready_for_review | approved | changes_requested | merged | closed | failed | archived
• review_state text not null default 'none'
  • none | needs_board_review | approved | changes_requested
• is_primary boolean not null default false
• health_status text not null default 'unknown'
  • unknown | healthy | unhealthy
• summary text null
• metadata jsonb null
• created_by_run_id uuid null
• created_at timestamptz not null default now()
• updated_at timestamptz not null default now()

Foreign keys

• company_id -> companies.id
• project_id -> projects.id on delete set null
• issue_id -> issues.id on delete cascade
• execution_workspace_id -> execution_workspaces.id on delete set null
• runtime_service_id -> workspace_runtime_services.id on delete set null
• created_by_run_id -> heartbeat_runs.id on delete set null

Indexes

• (company_id, issue_id, type)
• (company_id, execution_workspace_id, type)
• (company_id, provider, external_id)
• (company_id, updated_at desc)

5. Extend workspace_runtime_services

This table already exists and should remain the system of record for owned/tracked services.

New column

• execution_workspace_id uuid null

Foreign key

• execution_workspace_id -> execution_workspaces.id on delete set null

Behavior

• runtime services remain workspace-first
• issue UIs should surface them through linked execution workspaces and work products

Shared Contracts

1. packages/shared

Update project workspace types and validators

Add fields:

• sourceType
• defaultRef
• visibility
• setupCommand
• cleanupCommand
• remoteProvider
• remoteWorkspaceRef
• sharedWorkspaceKey

Add execution workspace types and validators

New shared types:

• ExecutionWorkspace
• ExecutionWorkspaceMode
• ExecutionWorkspaceStatus
• ExecutionWorkspaceProviderType

Add work product types and validators

New shared types:

• IssueWorkProduct
• IssueWorkProductType
• IssueWorkProductStatus
• IssueWorkProductReviewState

Update issue types and validators

Add:

• projectWorkspaceId
• executionWorkspaceId
• executionWorkspacePreference
• workProducts?: IssueWorkProduct[]

Extend project execution policy contract

Replace the current narrow policy with a more explicit shape:

• enabled
• defaultMode
  • shared_workspace | isolated_workspace | operator_branch | adapter_default
• allowIssueOverride
• defaultProjectWorkspaceId
• workspaceStrategy
• branchPolicy
• pullRequestPolicy
• runtimePolicy
• cleanupPolicy

Do not try to encode every possible provider-specific field in V1. Keep provider-specific extensibility in nested JSON where needed.

Service Layer Changes

1. Project service

Update project workspace CRUD to handle the extended schema.

Required rules

• when setting a primary workspace, clear is_primary on siblings
• source_type=remote_managed may have null cwd
• local/git-backed workspaces should still require one of cwd or repo_url
• preserve current behavior for existing callers that only send cwd/repoUrl/repoRef

2. Issue service

Update create/update flows to handle explicit workspace binding.

Create behavior

Resolve defaults in this order:

1. explicit projectWorkspaceId from request
2. project.executionWorkspacePolicy.defaultProjectWorkspaceId
3. project's primary workspace
4. null

Resolve executionWorkspacePreference:

1. explicit request field
2. project policy default
3. compatibility fallback to inherit

Do not create an execution workspace at issue creation time unless:

• reuse_existing is explicitly chosen and executionWorkspaceId is provided

Otherwise, workspace realization happens when execution starts.

Update behavior

• allow changing projectWorkspaceId only if the workspace belongs to the same project
• allow setting executionWorkspaceId only if it belongs to the same company and project
• do not automatically destroy or relink historical work products when workspace linkage changes

3. Workspace realization service

Refactor workspace-runtime.ts so realization produces or reuses an execution_workspaces row.

New flow

Input:

• issue
• project workspace
• project execution policy
• execution topology hint
• adapter/runtime configuration

Output:

• realized execution workspace record
• runtime cwd/provider metadata

Required modes

• shared_workspace
  • reuse a stable execution workspace representing the project primary/shared workspace
• isolated_workspace
  • create or reuse a derived isolated execution workspace
• operator_branch
  • create or reuse a long-lived branch workspace
• adapter_managed
  • create an execution workspace with provider references and optional null cwd
• cloud_sandbox
  • same as adapter-managed, but explicit remote sandbox semantics

Reuse rules

When reuse_existing is requested:

• only list active or recently used execution workspaces
• only for the same project
• only for the same project workspace if one is specified
• exclude archived and cleanup-failed workspaces

Shared workspace realization

For compatibility mode and shared-workspace projects:

• create a stable execution workspace per project workspace when first needed
• reuse it for subsequent runs

This avoids a special-case branch in later work product linkage.

4. Runtime service integration

When runtime services are started or reused:

• populate execution_workspace_id
• continue populating project_workspace_id, project_id, and issue_id

When a runtime service yields a URL:

• optionally create or update a linked issue_work_products row of type runtime_service or preview_url

5. PR and preview reporting

Add a service for creating/updating issue_work_products.

Supported V1 product types

• pull_request
• preview_url
• runtime_service
• branch
• commit
• artifact
• document

GitHub PR reporting

For V1, GitHub is the only provider with richer semantics.

Supported statuses:

• draft
• ready_for_review
• approved
• changes_requested
• merged
• closed

Represent these in status and review_state rather than inventing a separate PR table in V1.

Routes and API

1. Project workspace routes

Extend existing routes:

• GET /projects/:id/workspaces
• POST /projects/:id/workspaces
• PATCH /projects/:id/workspaces/:workspaceId
• DELETE /projects/:id/workspaces/:workspaceId

New accepted/returned fields

• sourceType
• defaultRef
• visibility
• setupCommand
• cleanupCommand
• remoteProvider
• remoteWorkspaceRef

2. Execution workspace routes

Add:

• GET /companies/:companyId/execution-workspaces
  • filters:
    • projectId
    • projectWorkspaceId
    • status
    • issueId
    • reuseEligible=true
• GET /execution-workspaces/:id
• PATCH /execution-workspaces/:id
  • update status/metadata/cleanup fields only in V1

Do not add top-level navigation for these routes yet.

3. Work product routes

Add:

• GET /issues/:id/work-products
• POST /issues/:id/work-products
• PATCH /work-products/:id
• DELETE /work-products/:id

V1 mutation permissions

• board can create/update/delete all
• agents can create/update for issues they are assigned or currently executing
• deletion should generally archive rather than hard-delete once linked to historical output

4. Issue routes

Extend existing create/update payloads to accept:

• projectWorkspaceId
• executionWorkspacePreference
• executionWorkspaceId

Extend GET /issues/:id to return:

• projectWorkspaceId
• executionWorkspaceId
• executionWorkspacePreference
• currentExecutionWorkspace
• workProducts[]

5. Instance settings routes

Add support for:

• reading/writing experimental.workspaces

This is a UI gate only.

If there is no generic instance settings storage yet, the first slice can store this in the existing config/instance settings mechanism used by /instance/settings.

UI Changes

1. /instance/settings

Add section:

• Experimental
  • Enable Workspaces

When off:

• hide new workspace-specific affordances
• do not alter existing project or issue behavior

2. Project properties

Do not create a separate Code tab yet. Ship inside existing project properties first.

Add or re-enable sections

• Project Workspaces
• Execution Defaults
• Provisioning
• Pull Requests
• Previews and Runtime
• Cleanup

Display rules

• only show when experimental.workspaces=true
• keep wording generic enough for local and remote setups
• only show git-specific fields when sourceType=git_repo
• only show local-path-specific fields when not remote_managed

3. Issue create dialog

When the workspace experimental flag is on and the selected project has workspace automation or workspaces:

Basic fields

• Codebase
  • select from project workspaces
  • default to policy default or primary workspace
• Execution mode
  • Project default
  • Shared workspace
  • Isolated workspace
  • Operator branch

Advanced section

• Reuse existing execution workspace

This control should query only:

• same project
• same codebase if selected
• active/recent workspaces
• compact labels with branch or workspace name

Do not expose all execution workspaces in a noisy unfiltered list.

4. Issue detail

Add a Work Product tab when:

• the experimental flag is on, or
• the issue already has work products

Show

• current execution workspace summary
• PR cards
• preview cards
• branch/commit rows
• artifacts/documents

Add compact header chips:

• codebase
• workspace
• PR count/status
• preview status

5. Execution workspace detail page

Add a detail route but no nav item.

Linked from:

• issue work product tab
• project workspace/execution panels

Show

• identity and status
• project workspace origin
• source issue
• linked issues
• branch/ref/provider info
• runtime services
• work products
• cleanup state

Runtime and Adapter Behavior

1. Local adapters

For local adapters:

• continue to use existing cwd/worktree realization paths
• persist the result as execution workspaces
• attach runtime services and work product to the execution workspace and issue

2. Remote or cloud adapters

For remote adapters:

• allow execution workspaces with null cwd
• require provider metadata sufficient to identify the remote workspace/session
• allow work product creation without any host-local process ownership

Examples:

• cloud coding agent opens a branch and PR on GitHub
• Vercel preview URL is reported back as a preview work product
• remote sandbox emits artifact URLs

3. Approval-aware PR workflow

V1 should support richer PR state tracking, but not a full review engine.

Required actions

• open_pr
• mark_ready

Required review states

• draft
• ready_for_review
• approved
• changes_requested
• merged
• closed

Storage approach

• represent these as issue_work_products with type='pull_request'
• use status and review_state
• store provider-specific details in metadata

Migration Plan

1. Existing installs

The migration posture is backward-compatible by default.

Guarantees

• no existing project must be edited before it keeps working
• no existing issue flow should start requiring workspace input
• all new nullable columns must preserve current behavior when absent

2. Project workspace migration

Migrate project_workspaces in place.

Backfill

• derive source_type
• copy repo_ref to default_ref
• leave new optional fields null

3. Issue migration

Do not backfill project_workspace_id or execution_workspace_id on all existing issues.

Reason:

• the safest migration is to preserve current runtime behavior and bind explicitly only when new workspace-aware flows are used

Interpret old issues as:

• executionWorkspacePreference = inherit
• compatibility/shared behavior

4. Runtime history migration

Do not attempt a perfect historical reconstruction of execution workspaces in the migration itself.

Instead:

• create execution workspace records forward from first new run
• optionally add a later backfill tool for recent runtime services if it proves valuable

Rollout Order

Phase 1: Schema and shared contracts

1. extend project_workspaces
2. add execution_workspaces
3. add issue_work_products
4. extend issues
5. extend workspace_runtime_services
6. update shared types and validators

Phase 2: Service wiring

1. update project workspace CRUD
2. update issue create/update resolution
3. refactor workspace realization to persist execution workspaces
4. attach runtime services to execution workspaces
5. add work product service and persistence

Phase 3: API and UI

1. add execution workspace routes
2. add work product routes
3. add instance experimental settings toggle
4. re-enable and revise project workspace UI behind the flag
5. add issue create/update controls behind the flag
6. add issue work product tab
7. add execution workspace detail page

Phase 4: Provider integrations

1. GitHub PR reporting
2. preview URL reporting
3. runtime-service-to-work-product linking
4. remote/cloud provider references

Acceptance Criteria

1. Existing installs continue to behave predictably with no required reconfiguration.
2. Projects can define local, git, non-git, and remote-managed project workspaces.
3. Issues can explicitly select a project workspace and execution preference.
4. Each issue can point to one current execution workspace.
5. Multiple issues can intentionally reuse the same execution workspace.
6. Execution workspaces are persisted for both local and remote execution flows.
7. Work products can be attached to issues with optional execution workspace linkage.
8. GitHub PRs can be represented with richer lifecycle states.
9. The main UI remains simple when the experimental flag is off.
10. No top-level workspace navigation is required for this first slice.

Risks and Mitigations

Risk: too many overlapping workspace concepts

Mitigation:

• keep issue UI to Codebase and Execution mode
• reserve execution workspace details for advanced pages

Risk: breaking current projects on upgrade

Mitigation:

• nullable schema additions
• in-place project_workspaces migration
• compatibility defaults

Risk: local-only assumptions leaking into cloud mode

Mitigation:

• make cwd optional for execution workspaces
• use provider_type and provider_ref
• use PAPERCLIP_EXECUTION_TOPOLOGY as a defaulting guardrail

Risk: turning PRs into a bespoke subsystem too early

Mitigation:

• represent PRs as work products in V1
• keep provider-specific details in metadata
• defer a dedicated PR table unless usage proves it necessary

Recommended First Engineering Slice

If we want the narrowest useful implementation:

1. extend project_workspaces
2. add execution_workspaces
3. extend issues with explicit workspace fields
4. persist execution workspaces from existing local workspace realization
5. add issue_work_products
6. show project workspace controls and issue workspace controls behind the experimental flag
7. add issue Work Product tab with PR/preview/runtime service display

This slice is enough to validate the model without yet building every provider integration or cleanup workflow.