# Workspace Product Model, Work Product, and PR Flow

## Context

Paperclip needs to support two very different but equally valid ways of working:

- a solo developer working directly on `master`, or in a folder that is not even a git repo
- a larger engineering workflow with isolated branches, previews, pull requests, and cleanup automation

Today, Paperclip already has the beginnings of this model:

- `projects` can carry execution workspace policy
- `project_workspaces` already exist as a durable project-scoped object
- issues can carry execution workspace settings
- runtime services can be attached to a workspace or issue

What is missing is a clear product model and UI that make these capabilities understandable and operable.

The main product risk is overloading one concept to do too much:

- making subissues do the job of branches or PRs
- making projects too infrastructure-heavy
- making workspaces so hidden that users cannot form a mental model
- making Paperclip feel like a code review tool instead of a control plane

## Goals

1. Keep `project` lightweight enough to remain a planning container.
2. Make workspace behavior understandable for both git and non-git projects.
3. Support three real workflows without forcing one:
   - shared workspace / direct-edit workflows
   - isolated issue workspace workflows
   - long-lived branch or operator integration workflows
4. Provide a first-class place to see the outputs of work:
   - previews
   - PRs
   - branches
   - commits
   - documents and artifacts
5. Keep the main navigation and task board simple.
6. Seamlessly upgrade existing Paperclip users to the new model without forcing disruptive reconfiguration.
7. Support cloud-hosted Paperclip deployments where execution happens in remote or adapter-managed environments rather than local workers.

## Non-Goals

- Turning Paperclip into a full code review product
- Requiring every issue to have its own branch or PR
- Requiring every project to configure code/workspace automation
- Making workspaces a top-level global navigation primitive in V1
- Requiring a local filesystem path or local git checkout to use workspace-aware execution

## Core Product Decisions

### 1. Project stays the planning object

A `project` remains the thing that groups work around a deliverable or initiative.

It may have:

- no code at all
- one default codebase/workspace
- several codebases/workspaces

Projects are not required to become heavyweight.

### 2. Project workspace is a first-class object, but scoped under project

A `project workspace` is the durable codebase or root environment for a project.

Examples:

- a local folder on disk
- a git repo checkout
- a monorepo package root
- a non-git design/doc folder
- a remote adapter-managed codebase reference

This is the stable anchor that operators configure once.

It should not be a top-level sidebar item in the main app. It should live under the project experience.

### 3. Execution workspace is a first-class runtime object

An `execution workspace` is where a specific run or issue actually executes.

Examples:

- the shared project workspace itself
- an isolated git worktree
- a long-lived operator branch checkout
- an adapter-managed remote sandbox
- a cloud agent provider's isolated branch/session environment

This object must be recorded explicitly so that Paperclip can:

- show where work happened
- attach previews and runtime services
- link PRs and branches
- decide cleanup behavior
- support reuse across multiple related issues

### 4. PRs are work product, not the core issue model

A PR is an output of work, not the planning unit.

Paperclip should treat PRs as a type of work product linked back to:

- the issue
- the execution workspace
- optionally the project workspace

Git-specific automation should live under workspace policy, not under the core issue abstraction.

### 5. Existing users must upgrade automatically

Paperclip already has users and existing project/task data. Any new model must preserve continuity.

The product should default existing installs into a sensible compatibility mode:

- existing projects without workspace configuration continue to work unchanged
- existing `project_workspaces` become the durable `project workspace` objects
- existing project execution workspace policy is mapped forward rather than discarded
- issues without explicit workspace fields continue to inherit current behavior

This migration should feel additive, not like a mandatory re-onboarding flow.

### 6. Cloud-hosted Paperclip must be a first-class deployment mode

Paperclip cannot assume that it is running on the same machine as the code.

In cloud deployments, Paperclip may:

- run on Vercel or another serverless host
- have no long-lived local worker process
- delegate execution to a remote coding agent or provider-managed sandbox
- receive back a branch, PR, preview URL, or artifact from that remote environment

The model therefore must be portable:

- `project workspace` may be remote-managed, not local
- `execution workspace` may have no local `cwd`
- `runtime services` may be tracked by provider reference and URL rather than a host process
- work product harvesting must handle externally owned previews and PRs

### 7. Subissues remain planning and ownership structure

Subissues are for decomposition and parallel ownership.

They are not the same thing as:

- a branch
- a worktree
- a PR
- a preview

They may correlate with those things, but they should not be overloaded to mean them.

## Terminology

Use these terms consistently in product copy:

- `Project`: planning container
- `Project workspace`: durable configured codebase/root
- `Execution workspace`: actual runtime workspace used for issue execution
- `Isolated issue workspace`: user-facing term for an issue-specific derived workspace
- `Work product`: previews, PRs, branches, commits, artifacts, docs
- `Runtime service`: a process or service Paperclip owns or tracks for a workspace

Use these terms consistently in migration and deployment messaging:

- `Compatible mode`: existing behavior preserved without new workspace automation
- `Adapter-managed workspace`: workspace realized by a remote or cloud execution provider

Avoid teaching users that "workspace" always means "git worktree on my machine".

## Product Object Model

## 1. Project

Existing object. No fundamental change in role.

### Required behavior

- can exist without code/workspace configuration
- can have zero or more project workspaces
- can define execution defaults that new issues inherit

### Proposed fields

- `id`
- `companyId`
- `name`
- `description`
- `status`
- `goalIds`
- `leadAgentId`
- `targetDate`
- `executionWorkspacePolicy`
- `workspaces[]`
- `primaryWorkspace`

## 2. Project Workspace

Durable, configured, project-scoped codebase/root object.

This should evolve from the current `project_workspaces` table into a more explicit product object.

### Motivation

This separates:

- "what codebase/root does this project use?"

from:

- "what temporary execution environment did this issue run in?"

That keeps the model simple for solo users while still supporting advanced automation.
It also lets cloud-hosted Paperclip deployments point at codebases and remotes without pretending the Paperclip host has direct filesystem access.

### Proposed fields

- `id`
- `companyId`
- `projectId`
- `name`
- `sourceType`
  - `local_path`
  - `git_repo`
  - `remote_managed`
  - `non_git_path`
- `cwd`
- `repoUrl`
- `defaultRef`
- `isPrimary`
- `visibility`
  - `default`
  - `advanced`
- `setupCommand`
- `cleanupCommand`
- `metadata`
- `createdAt`
- `updatedAt`

### Notes

- `sourceType=non_git_path` is important so non-git projects are first-class.
- `setupCommand` and `cleanupCommand` should be allowed here for workspace-root bootstrap, even when isolated execution is not used.
- For a monorepo, multiple project workspaces may point at different roots or packages under one repo.
- `sourceType=remote_managed` is important for cloud deployments where the durable codebase is defined by provider/repo metadata rather than a local checkout path.

## 3. Project Execution Workspace Policy

Project-level defaults for how issues execute.

This is the main operator-facing configuration surface.

### Motivation

This lets Paperclip support:

- direct editing in a shared workspace
- isolated workspaces for issue parallelism
- long-lived integration branch workflows
- remote cloud-agent execution that returns a branch or PR

without forcing every issue or agent to expose low-level runtime configuration.

### Proposed fields

- `enabled: boolean`
- `defaultMode`
  - `shared_workspace`
  - `isolated_workspace`
  - `operator_branch`
  - `adapter_default`
- `allowIssueOverride: boolean`
- `defaultProjectWorkspaceId: uuid | null`
- `workspaceStrategy`
  - `type`
    - `project_primary`
    - `git_worktree`
    - `adapter_managed`
  - `baseRef`
  - `branchTemplate`
  - `worktreeParentDir`
  - `provisionCommand`
  - `teardownCommand`
- `branchPolicy`
  - `namingTemplate`
  - `allowReuseExisting`
  - `preferredOperatorBranch`
- `pullRequestPolicy`
  - `mode`
    - `disabled`
    - `manual`
    - `agent_may_open_draft`
    - `approval_required_to_open`
    - `approval_required_to_mark_ready`
  - `baseBranch`
  - `titleTemplate`
  - `bodyTemplate`
- `runtimePolicy`
  - `allowWorkspaceServices`
  - `defaultServicesProfile`
  - `autoHarvestOwnedUrls`
- `cleanupPolicy`
  - `mode`
    - `manual`
    - `when_issue_terminal`
    - `when_pr_closed`
    - `retention_window`
  - `retentionHours`
  - `keepWhilePreviewHealthy`
  - `keepWhileOpenPrExists`

## 4. Issue Workspace Binding

Issue-level selection of execution behavior.

This should remain lightweight in the normal case and only surface richer controls when relevant.

### Motivation

Not every issue in a code project should create a new derived workspace.

Examples:

- a tiny fix can run in the shared workspace
- three related issues may intentionally share one integration branch
- a solo operator may be working directly on `master`

### Proposed fields on `issues`

- `projectWorkspaceId: uuid | null`
- `executionWorkspacePreference`
  - `inherit`
  - `shared_workspace`
  - `isolated_workspace`
  - `operator_branch`
  - `reuse_existing`
- `preferredExecutionWorkspaceId: uuid | null`
- `executionWorkspaceSettings`
  - keep advanced per-issue override fields here

### Rules

- if the project has no workspace automation, these fields may all be null
- if the project has one primary workspace, issue creation should default to it silently
- `reuse_existing` is advanced-only and should target active execution workspaces, not the whole workspace universe
- existing issues without these fields should behave as `inherit` during migration

## 5. Execution Workspace

A durable record for a shared or derived runtime workspace.

This is the missing object that makes cleanup, previews, PRs, and branch reuse tractable.

### Motivation

Without an explicit `execution workspace` record, Paperclip has nowhere stable to attach:

- derived branch/worktree identity
- active preview ownership
- PR linkage
- cleanup state
- "reuse this existing integration branch" behavior
- remote provider session identity

### Proposed new object

`execution_workspaces`

### Proposed fields

- `id`
- `companyId`
- `projectId`
- `projectWorkspaceId`
- `sourceIssueId`
- `mode`
  - `shared_workspace`
  - `isolated_workspace`
  - `operator_branch`
  - `adapter_managed`
- `strategyType`
  - `project_primary`
  - `git_worktree`
  - `adapter_managed`
- `name`
- `status`
  - `active`
  - `idle`
  - `in_review`
  - `archived`
  - `cleanup_failed`
- `cwd`
- `repoUrl`
- `baseRef`
- `branchName`
- `providerRef`
- `providerType`
  - `local_fs`
  - `git_worktree`
  - `adapter_managed`
  - `cloud_sandbox`
- `derivedFromExecutionWorkspaceId`
- `lastUsedAt`
- `openedAt`
- `closedAt`
- `cleanupEligibleAt`
- `cleanupReason`
- `metadata`
- `createdAt`
- `updatedAt`

### Notes

- `sourceIssueId` is the issue that originally caused the workspace to be created, not necessarily the only issue linked to it later.
- multiple issues may link to the same execution workspace in a long-lived branch workflow.
- `cwd` may be null for remote execution workspaces; provider identity and work product links still make the object useful.

## 6. Issue-to-Execution Workspace Link

An issue may need to link to one or more execution workspaces over time.

Examples:

- an issue begins in a shared workspace and later moves to an isolated one
- a failed attempt is archived and a new workspace is created
- several issues intentionally share one operator branch workspace

### Proposed object

`issue_execution_workspaces`

### Proposed fields

- `issueId`
- `executionWorkspaceId`
- `relationType`
  - `current`
  - `historical`
  - `preferred`
- `createdAt`
- `updatedAt`

### UI simplification

Most issues should only show one current workspace in the main UI. Historical links belong in advanced/history views.

## 7. Work Product

User-facing umbrella concept for outputs of work.

### Motivation

Paperclip needs a single place to show:

- "here is the preview"
- "here is the PR"
- "here is the branch"
- "here is the commit"
- "here is the artifact/report/doc"

without turning issues into a raw dump of adapter details.

### Proposed new object

`issue_work_products`

### Proposed fields

- `id`
- `companyId`
- `projectId`
- `issueId`
- `executionWorkspaceId`
- `runtimeServiceId`
- `type`
  - `preview_url`
  - `runtime_service`
  - `pull_request`
  - `branch`
  - `commit`
  - `artifact`
  - `document`
- `provider`
  - `paperclip`
  - `github`
  - `gitlab`
  - `vercel`
  - `netlify`
  - `custom`
- `externalId`
- `title`
- `url`
- `status`
  - `active`
  - `ready_for_review`
  - `merged`
  - `closed`
  - `failed`
  - `archived`
- `reviewState`
  - `none`
  - `needs_board_review`
  - `approved`
  - `changes_requested`
- `isPrimary`
- `healthStatus`
  - `unknown`
  - `healthy`
  - `unhealthy`
- `summary`
- `metadata`
- `createdByRunId`
- `createdAt`
- `updatedAt`

### Behavior

- PRs are stored here as `type=pull_request`
- previews are stored here as `type=preview_url` or `runtime_service`
- Paperclip-owned processes should update health/status automatically
- external providers should at least store link, provider, external id, and latest known state
- cloud agents should be able to create work product records without Paperclip owning the execution host

## Page and UI Model

## 1. Global Navigation

Do not add `Workspaces` as a top-level sidebar item in V1.

### Motivation

That would make the whole product feel infra-heavy, even for companies that do not use code automation.

### Global nav remains

- Dashboard
- Inbox
- Companies
- Agents
- Goals
- Projects
- Issues
- Approvals

Workspaces and work product should be surfaced through project and issue detail views.

## 2. Project Detail

Add a project sub-navigation that keeps planning first and code second.

### Tabs

- `Overview`
- `Issues`
- `Code`
- `Activity`

Optional future:

- `Outputs`

### `Overview` tab

Planning-first summary:

- project status
- goals
- lead
- issue counts
- top-level progress
- latest major work product summaries

### `Issues` tab

- default to top-level issues only
- show parent issue rollups:
  - child count
  - `x/y` done
  - active preview/PR badges
- optional toggle: `Show subissues`

### `Code` tab

This is the main workspace configuration and visibility surface.

#### Section: `Project Workspaces`

List durable project workspaces for the project.

Card/list columns:

- workspace name
- source type
- path or repo
- default ref
- primary/default badge
- active execution workspaces count
- active issue count
- active preview count
- hosting type / provider when remote-managed

Actions:

- `Add workspace`
- `Edit`
- `Set default`
- `Archive`

#### Section: `Execution Defaults`

Fields:

- `Enable workspace automation`
- `Default issue execution mode`
  - `Shared workspace`
  - `Isolated workspace`
  - `Operator branch`
  - `Adapter default`
- `Default codebase`
- `Allow issue override`

#### Section: `Provisioning`

Fields:

- `Setup command`
- `Cleanup command`
- `Implementation`
  - `Shared workspace`
  - `Git worktree`
  - `Adapter-managed`
- `Base ref`
- `Branch naming template`
- `Derived workspace parent directory`

Hide git-specific fields when the selected workspace is not git-backed.
Hide local-path-specific fields when the selected workspace is remote-managed.

#### Section: `Pull Requests`

Fields:

- `PR workflow`
  - `Disabled`
  - `Manual`
  - `Agent may open draft PR`
  - `Approval required to open PR`
  - `Approval required to mark ready`
- `Default base branch`
- `PR title template`
- `PR body template`

#### Section: `Previews and Runtime`

Fields:

- `Allow workspace runtime services`
- `Default services profile`
- `Harvest owned preview URLs`
- `Track external preview URLs`

#### Section: `Cleanup`

Fields:

- `Cleanup mode`
  - `Manual`
  - `When issue is terminal`
  - `When PR closes`
  - `After retention window`
- `Retention window`
- `Keep while preview is active`
- `Keep while PR is open`

## 3. Add Project Workspace Flow

Entry point: `Project > Code > Add workspace`

### Form fields

- `Name`
- `Source type`
  - `Local folder`
  - `Git repo`
  - `Non-git folder`
  - `Remote managed`
- `Local path`
- `Repository URL`
- `Remote provider`
- `Remote workspace reference`
- `Default ref`
- `Set as default workspace`
- `Setup command`
- `Cleanup command`

### Behavior

- if source type is non-git, hide branch/PR-specific setup
- if source type is git, show ref and optional advanced branch fields
- if source type is remote-managed, show provider/reference fields and hide local-path-only configuration
- for simple solo users, this can be one path field and one save button

## 4. Issue Create Flow

Issue creation should stay simple by default.

### Default behavior

If the selected project:

- has no workspace automation: show no workspace UI
- has one default project workspace and default execution mode: inherit silently

### Show a `Workspace` section only when relevant

#### Basic fields

- `Codebase`
  - default selected project workspace
- `Execution mode`
  - `Project default`
  - `Shared workspace`
  - `Isolated workspace`
  - `Operator branch`

#### Advanced-only field

- `Reuse existing execution workspace`

This dropdown should show only active execution workspaces for the selected project workspace, with labels like:

- `dotta/integration-branch`
- `PAP-447-add-worktree-support`
- `shared primary workspace`

### Important rule

Do not show a picker containing every possible workspace object by default.

The normal flow should feel like:

- choose project
- optionally choose codebase
- optionally choose execution mode

not:

- choose from a long mixed list of roots, derived worktrees, previews, and branch names

### Migration rule

For existing users, issue creation should continue to look the same until a project explicitly enables richer workspace behavior.

## 5. Issue Detail

Issue detail should expose workspace and work product clearly, but without becoming a code host UI.

### Header chips

Show compact summary chips near the title/status area:

- `Codebase: Web App`
- `Workspace: Shared`
- `Workspace: PAP-447-add-worktree-support`
- `PR: Open`
- `Preview: Healthy`

### Tabs

- `Comments`
- `Subissues`
- `Work Product`
- `Activity`

### `Work Product` tab

Sections:

- `Current workspace`
- `Previews`
- `Pull requests`
- `Branches and commits`
- `Artifacts and documents`

#### Current workspace panel

Fields:

- workspace name
- mode
- branch
- base ref
- last used
- linked issues count
- cleanup status

Actions:

- `Open workspace details`
- `Mark in review`
- `Request cleanup`

#### Pull request cards

Fields:

- title
- provider
- status
- review state
- linked branch
- open/ready/merged timestamps

Actions:

- `Open PR`
- `Refresh status`
- `Request board review`

#### Preview cards

Fields:

- title
- URL
- provider
- health
- ownership
- updated at

Actions:

- `Open preview`
- `Refresh`
- `Archive`

## 6. Execution Workspace Detail

This can be reached from a project code tab or an issue work product tab.

It does not need to be in the main sidebar.

### Sections

- identity
- source issue
- linked issues
- branch/ref
- provider/session identity
- active runtime services
- previews
- PRs
- cleanup state
- event/activity history

### Motivation

This is where advanced users go when they need to inspect the mechanics. Most users should not need it in normal flow.

## 7. Inbox Behavior

Inbox should surface actionable work product events, not every implementation detail.

### Show inbox items for

- issue assigned or updated
- PR needs board review
- PR opened or marked ready
- preview unhealthy
- workspace cleanup failed
- runtime service failed
- remote cloud-agent run returned PR or preview that needs review

### Do not show by default

- every workspace heartbeat
- every branch update
- every derived workspace creation

### Display style

If the inbox item is about a preview or PR, show issue context with it:

- issue identifier and title
- parent issue if this is a subissue
- workspace name if relevant

## 8. Issues List and Kanban

Keep list and board planning-first.

### Default behavior

- show top-level issues by default
- show parent rollups for subissues
- do not flatten every child execution detail into the main board

### Row/card adornments

For issues with linked work product, show compact badges:

- `1 PR`
- `2 previews`
- `shared workspace`
- `isolated workspace`

### Optional advanced filters

- `Has PR`
- `Has preview`
- `Workspace mode`
- `Codebase`

## Upgrade and Migration Plan

## 1. Product-level migration stance

Migration must be silent-by-default and compatibility-preserving.

Existing users should not be forced to:

- create new workspace objects by hand before they can keep working
- re-tag old issues
- learn new workspace concepts before basic issue flows continue to function

## 2. Existing project migration

On upgrade:

- existing `project_workspaces` records are retained and shown as `Project Workspaces`
- the current primary workspace remains the default codebase
- existing project execution workspace policy is mapped into the new `Project Execution Workspace Policy` surface
- projects with no execution workspace policy stay in compatible/shared mode

## 3. Existing issue migration

On upgrade:

- existing issues default to `executionWorkspacePreference=inherit`
- if an issue already has execution workspace settings, map them forward directly
- if an issue has no explicit workspace data, preserve existing behavior and do not force a user-visible choice

## 4. Existing run/runtime migration

On upgrade:

- active or recent runtime services can be backfilled into execution workspace history where feasible
- missing history should not block rollout; forward correctness matters more than perfect historical reconstruction

## 5. Rollout UX

Use additive language in the UI:

- `Code`
- `Workspace automation`
- `Optional`
- `Advanced`

Avoid migration copy that implies users were previously using the product "wrong".

## Cloud Deployment Requirements

## 1. Paperclip host and execution host must be decoupled

Paperclip may run:

- locally with direct filesystem access
- in a cloud app host such as Vercel
- in a hybrid setup with external job runners

The workspace model must work in all three.

## 2. Remote execution must support first-class work product reporting

A cloud agent should be able to:

- resolve a project workspace
- realize an adapter-managed execution workspace remotely
- produce a branch
- open or update a PR
- emit preview URLs
- register artifacts

without the Paperclip host itself running local git or local preview processes.

## 3. Local-only assumptions must be optional

The following must be optional, not required:

- local `cwd`
- local git CLI
- host-managed worktree directories
- host-owned long-lived preview processes

## 4. Same product surface, different provider behavior

The UI should not split into "local mode" and "cloud mode" products.

Instead:

- local projects show path/git implementation details
- cloud projects show provider/reference details
- both surface the same high-level objects:
  - project workspace
  - execution workspace
  - work product
  - runtime service or preview

## Patterns Learned from Worktrunk

Worktrunk is a useful reference point because it is unapologetically focused on git-worktree-based developer workflows.

Paperclip should not copy its product framing wholesale, but there are several good patterns worth applying.

References:

- `https://worktrunk.dev/tips-patterns/`
- `https://github.com/max-sixty/worktrunk`

## 1. Deterministic per-workspace resources

Worktrunk treats a derived workspace as something that can deterministically own:

- ports
- local URLs
- databases
- runtime process identity

This is a strong pattern for Paperclip.

### Recommendation

Execution workspaces should be able to deterministically derive and expose:

- preview URLs
- port allocations
- database/schema names
- runtime service reuse keys

This makes previews and local runtime services more predictable and easier to manage across many parallel workspaces.

## 2. Lifecycle hooks should stay simple and explicit

Worktrunk uses practical lifecycle hooks such as create/start/remove/merge-oriented commands.

The main lesson is not to build a huge workflow engine. The lesson is to give users a few well-defined lifecycle moments to attach automation to.

### Recommendation

Paperclip should keep workspace automation centered on a small set of hooks:

- `setup`
- `cleanup`
- optionally `before_review`
- optionally `after_merge` or `after_close`

These should remain project/workspace policy concerns, not agent-prompt conventions.

## 3. Workspace status visibility is a real product feature

Worktrunk's listing/status experience is doing important product work:

- which workspaces exist
- what branch they are on
- what services or URLs they own
- whether they are active or stale

### Recommendation

Paperclip should provide the equivalent visibility in the project `Code` surface:

- active execution workspaces
- linked issues
- linked PRs
- linked previews/runtime services
- cleanup eligibility

This reinforces why `execution workspace` needs to be a first-class recorded object.

## 4. Execution workspaces are runtime islands, not just checkouts

One of Worktrunk's strongest implicit ideas is that a worktree is not only code. It often owns an entire local runtime environment.

### Recommendation

Paperclip should treat execution workspaces as the natural home for:

- dev servers
- preview processes
- sandbox credentials or provider references
- branch/ref identity
- local or remote environment bootstrap

This supports the `work product` model and the preview/runtime service model proposed above.

## 5. Machine-readable workspace state matters

Worktrunk exposes structured state that can be consumed by tools and automation.

### Recommendation

Paperclip should ensure that execution workspaces and work product have clean structured API surfaces, not just UI-only representation.

That is important for:

- agents
- CLIs
- dashboards
- future automation and cleanup tooling

## 6. Cleanup should be first-class, not an afterthought

Worktrunk makes create/remove/merge cleanup part of the workflow.

### Recommendation

Paperclip should continue treating cleanup policy as part of the core workspace model:

- when is cleanup allowed
- what blocks cleanup
- what gets archived versus destroyed
- what happens when cleanup fails

This validates the explicit cleanup policy proposed earlier in this plan.

## 7. What not to copy

There are also important limits to the analogy.

Paperclip should not adopt these Worktrunk assumptions as universal product rules:

- every execution workspace is a local git worktree
- the Paperclip host has direct shell and filesystem access
- every workflow is merge-centric
- every user wants developer-tool-level workspace detail in the main navigation

### Product implication

Paperclip should borrow Worktrunk's good execution patterns while keeping the broader Paperclip model:

- project plans the work
- workspace defines where work happens
- work product defines what came out
- git worktree remains one implementation strategy, not the product itself

## Behavior Rules

## 1. Cleanup must not depend on agents remembering `in_review`

Agents may still use `in_review`, but cleanup behavior must be governed by policy and observed state.

### Keep an execution workspace alive while any of these are true

- a linked issue is non-terminal
- a linked PR is open
- a linked preview/runtime service is active
- the workspace is still within retention window

### Hide instead of deleting aggressively

Archived or idle workspaces should be hidden from default lists before they are hard-cleaned up.

## 2. Multiple issues may intentionally share one execution workspace

This is how Paperclip supports:

- solo dev on a shared branch
- operator integration branches
- related features batched into one PR

This is the key reason not to force 1 issue = 1 workspace = 1 PR.

## 3. Isolated issue workspaces remain opt-in

Even in a git-heavy project, isolated workspaces should be optional.

Examples where shared mode is valid:

- tiny bug fixes
- branchless prototyping
- non-git projects
- single-user local workflows

## 4. PR policy belongs to git-backed workspace policy

PR automation decisions should be made at the project/workspace policy layer.

The issue should only:

- surface the resulting PR
- route approvals/review requests
- show status and review state

## 5. Work product is the user-facing unifier

Previews, PRs, commits, and artifacts should all be discoverable through one consistent issue-level affordance.

That keeps Paperclip focused on coordination and visibility instead of splitting outputs across many hidden subsystems.

## Recommended Implementation Order

## Phase 1: Clarify current objects in UI

1. Surface `Project > Code` tab
2. Show existing project workspaces there
3. Re-enable project-level execution workspace policy with revised copy
4. Keep issue creation simple with inherited defaults

## Phase 2: Add explicit execution workspace record

1. Add `execution_workspaces`
2. Link runs, issues, previews, and PRs to it
3. Add simple execution workspace detail page
4. Make `cwd` optional and ensure provider-managed remote workspaces are supported from day one

## Phase 3: Add work product model

1. Add `issue_work_products`
2. Ingest PRs, previews, branches, commits
3. Add issue `Work Product` tab
4. Add inbox items for actionable work product state changes
5. Support remote agent-created PR/preview reporting without local ownership

## Phase 4: Add advanced reuse and cleanup workflows

1. Add `reuse existing execution workspace`
2. Add cleanup lifecycle UI
3. Add operator branch workflow shortcuts
4. Add richer external preview harvesting
5. Add migration tooling/backfill where it improves continuity for existing users

## Why This Model Is Right

This model keeps the product balanced:

- simple enough for solo users
- strong enough for real engineering teams
- flexible for non-git projects
- explicit enough to govern PRs and previews

Most importantly, it keeps the abstractions clean:

- projects plan the work
- project workspaces define the durable codebases
- execution workspaces define where work ran
- work product defines what came out of the work
- PRs remain outputs, not the core task model

It also keeps the rollout practical:

- existing users can upgrade without workflow breakage
- local-first installs stay simple
- cloud-hosted Paperclip deployments remain first-class

That is a better fit for Paperclip than either extreme:

- hiding workspace behavior until nobody understands it
- or making the whole app revolve around code-host mechanics