Document canonical workspace server decision

Docs/Design/Canonical_Workspace_Server_Record_Decision_2026_07.md

@@ -0,0 +1,111 @@
+# Canonical Workspace Server Record Decision - July 2026
+
+Date: 2026-07-04
+Status: Accepted
+Tracking: [#1526](https://github.com/rmusser01/tldw_server/issues/1526)
+
+## Decision
+
+The canonical workspace product model is the server `Workspace` record exposed by
+the `/api/v1/workspaces` API family. `/research-workspace` is the canonical
+research shell that consumes that model.
+
+`WorkspacePlayground` is not the canonical shell. The legacy
+`workspace_playground` label and `tldw.workspace-playground.bundle` payloads are
+compatibility inputs only. The `/workspace-playground` route must remain removed
+with no alias and no redirect.
+
+`ChatWorkspace` and `DocumentWorkspace` may remain specialized entry points, but
+they must not define separate workspace identity, membership, lifecycle, or
+runtime-handoff semantics. Future route consolidation needs a superseding
+decision record only if ownership changes.
+
+## Server And Local Boundary
+
+The minimum server-backed workspace record is already defined by
+`Docs/Design/Workspace_Container_Contract_2026_06.md`:
+
+- `workspace_id` as the stable product identity.
+- `name`, `workspace_profile`, lifecycle flags, version, and timestamps.
+- membership rows for sources, artifacts, chats, prompts, workflows,
+  watchlists, ACP sessions, and Sandbox sessions where adapters exist.
+- source status, notes, artifacts, roots, capabilities, context, eligibility,
+  runtime bindings, and activity/index read models through the Workspaces API.
+
+Browser-local workspace state remains a cache and UI state layer. It may store
+drafts, layout, local split-key payloads, import/export recovery state, and
+offline-friendly snapshots. It is not authoritative for membership, lifecycle,
+runtime trust, ACP admission, Sandbox admission, MCP policy, or cross-device
+ownership.
+
+Local-only or imported workspaces must materialize or reconcile a server
+workspace record before cross-surface handoff. The server ID is the handoff key.
+
+## Handoff Map
+
+| Surface | Contract |
+| --- | --- |
+| Research Workspace | Uses server `workspace_id` for source selection, chat grounding, studio artifacts, notes, import/export, and extension capture landing. |
+| ACP Agent Tasks and ACP Playground | Use `/api/v1/agent-orchestration/workspaces/canonical-bridge` and canonical workspace filters. ACP owns execution roots, projects, tasks, runs, sessions, diagnostics, audit, reviewer state, and promoted artifacts. |
+| MCP Hub | Owns workspace sets, path/tool trust, policy assignment, and tool execution. It may bind to the canonical workspace ID but does not become the source-membership owner. |
+| Sandbox | Owns admission, runtime/session lifecycle, run creation, diagnostics, and isolation. Workspace context is an input, not a trust grant. |
+| Browser extension capture | Targets canonical workspace/source IDs and deep-links to `/research-workspace`. |
+| Chatbooks and migration | Use workspace bundles, migration receipts, and compatibility imports; they do not create a second workspace identity model. |
+| ChatWorkspace and DocumentWorkspace | May link or promote resources into the server workspace model; they do not own a competing model. |
+
+## Current State
+
+Existing records and evidence already close the model-design portion of #1526:
+
+- `Docs/Design/Workspace_Canonical_Model_Decision_2026_05.md` selected
+  `ResearchWorkspace` as the first-slice canonical shell.
+- `Docs/Design/Research_Workspace_Shared_Workspace_Model_Contract_2026_05.md`
+  defines cross-domain ownership boundaries for Workspaces, Research Workspace,
+  Shared Workspaces, MCP Hub, ACP, and Sandbox.
+- `Docs/Design/Workspace_Container_Contract_2026_06.md` defines the Phase 2
+  server Workspace record, membership contract, runtime binding vocabulary,
+  active-context eligibility rules, and surface mapping.
+- `Docs/superpowers/specs/2026-06-18-workspace-frontend-server-context-contract-design.md`
+  records the frontend decision to unify on the server Workspace model.
+- `Docs/Reviews/RESEARCH_WORKSPACE_LIVE_UAT_MATRIX_2026_05_25.md` records live
+  evidence for the canonical route, source lifecycle, ACP bridge, MCP handoff,
+  Sandbox diagnostics, extension capture, migration/import/export, and current
+  remaining Partial rows.
+
+The remaining work is certification and product hardening, not a new workspace
+architecture.
+
+## Follow-Up Issues
+
+- [#2605](https://github.com/rmusser01/tldw_server/issues/2605): certify the
+  repeatable final Research Workspace UAT runner or accepted full fallback.
+- [#2606](https://github.com/rmusser01/tldw_server/issues/2606): complete
+  beginner/no-key UAT certification.
+- [#2607](https://github.com/rmusser01/tldw_server/issues/2607): complete
+  authenticated power-user UAT certification.
+- [#2608](https://github.com/rmusser01/tldw_server/issues/2608): live recheck
+  destructive and recovery actions.
+
+## Guardrails
+
+- Do not reintroduce `/workspace-playground`, aliases, redirects, or current UI
+  copy that treats Workspace Playground as active.
+- Do not use active workspace selection as a silent global filter for Library,
+  Notes, Media, Artifacts, Chat, Prompts, Workflows, Watchlists, ACP, Sandbox, or
+  MCP browse/search surfaces.
+- Do not move ACP, MCP, Sandbox, Jobs, or owner-domain CRUD into the Workspaces
+  module.
+- Do not persist secrets, raw environment values, unrestricted filesystem paths,
+  prompt bodies, model outputs, or file contents in workspace membership or
+  public runtime-binding metadata.
+- Add new follow-up issues only when implementation discovers a real contract
+  gap that is not already covered by the documents or child issues above.
+
+## #1526 Acceptance Mapping
+
+| #1526 acceptance item | Status |
+| --- | --- |
+| Canonical workspace model and route strategy | Server Workspace model is canonical; `/research-workspace` is the canonical research shell; Workspace Playground is compatibility-only. |
+| Server/local bridge requirements | Server identity, membership, lifecycle, context, eligibility, runtime descriptors, and activity/index are authoritative; local state is cache/UI/recovery only. |
+| Existing trackers linked without duplicate scope | This record links the existing May/June decisions, frontend contract, and UAT matrix instead of redefining them. |
+| Follow-up issues are reviewable | #2605, #2606, #2607, and #2608 are narrow certification/recheck issues. |

backlog/tasks/task-12128 - Document-canonical-workspace-decision-for-GitHub-issue-1526.md

@@ -0,0 +1,55 @@
+---
+id: TASK-12128
+title: Document canonical workspace decision for GitHub issue 1526
+status: Done
+labels:
+- docs
+- workspace
+- roadmap
+references:
+- https://github.com/rmusser01/tldw_server/issues/1526
+- https://github.com/rmusser01/tldw_server/issues/2605
+- https://github.com/rmusser01/tldw_server/issues/2606
+- https://github.com/rmusser01/tldw_server/issues/2607
+- https://github.com/rmusser01/tldw_server/issues/2608
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Create a concise decision record for GitHub issue #1526 that codifies the server Workspace model and /research-workspace route strategy, links existing specs/UAT evidence, and identifies only narrow follow-up issues for remaining certification gaps.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Decision record identifies canonical workspace model and route strategy.
+- [x] #2 Server/local workspace bridge requirements are documented with minimum API/storage shape.
+- [x] #3 Existing workspace-related trackers/specs/UAT evidence are linked without duplicating implementation scope.
+- [x] #4 Follow-up implementation issues are small enough for reviewable PRs.
+<!-- AC:END -->
+
+## Implementation Notes
+
+<!-- SECTION:IMPLEMENTATION_NOTES:BEGIN -->
+- Worktree: `.worktrees/codex-workspace-decision-record`
+- Branch: `codex/workspace-decision-record`
+- Follow-up issues created: #2605, #2606, #2607, #2608.
+<!-- SECTION:IMPLEMENTATION_NOTES:END -->
+
+## Final Summary
+
+<!-- SECTION:FINAL_SUMMARY:BEGIN -->
+- Added `Docs/Design/Canonical_Workspace_Server_Record_Decision_2026_07.md`.
+- Created follow-up issues #2605, #2606, #2607, and #2608 for the remaining certification/recheck work.
+- Verification: `git diff --cached --check` passed. Bandit skipped because this is a docs/backlog-only change.
+<!-- SECTION:FINAL_SUMMARY:END -->
+
+## Definition of Done
+<!-- DOD:BEGIN -->
+- [x] #1 Acceptance criteria completed
+- [x] #2 Tests or verification recorded
+- [x] #3 Documentation updated when relevant
+- [x] #4 Bandit run for touched code when applicable or document non-code/environment skip
+- [x] #5 Final summary added
+- [x] #6 Known skips or blockers documented
+<!-- DOD:END -->