From 284bd733b9b610381c4759b7adde7d21ece34969 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Fri, 13 Mar 2026 08:41:01 -0500
Subject: [PATCH] Add workspace product model plan

---
 ...orkspace-product-model-and-work-product.md | 959 ++++++++++++++++++
 1 file changed, 959 insertions(+)
 create mode 100644 doc/plans/workspace-product-model-and-work-product.md

diff --git a/doc/plans/workspace-product-model-and-work-product.md b/doc/plans/workspace-product-model-and-work-product.md
new file mode 100644
index 00000000..3b201e7d
--- /dev/null
+++ b/doc/plans/workspace-product-model-and-work-product.md
@@ -0,0 +1,959 @@
+# 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.
+
+## 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
+
+## 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
+
+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. 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
+
+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.
+
+### 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.
+
+## 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
+
+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
+
+## 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
+
+### 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`
+- `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.
+
+## 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
+
+## 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
+
+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.
+
+#### 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`
+- `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
+- 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
+
+## 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
+- 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
+
+### 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`
+
+## 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
+
+## 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
+
+## 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
+
+## 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
+
+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