diff --git a/docs/review-context/07-workspace-product-model.md b/docs/review-context/07-workspace-product-model.md index a464b9b8..6aaf85f6 100644 --- a/docs/review-context/07-workspace-product-model.md +++ b/docs/review-context/07-workspace-product-model.md @@ -57,6 +57,16 @@ VULCA should combine: It should not become a generic file review tool or an editor replacement. +## Production Persistence Layer + +Production persistence is part of the Workspace product design, not a separate +backend-only concern. It defines durable Creative Repo state, reviewer and +release-owner permissions, conflict handling, multi-instance behavior, and +audit history. + +Use `15-workspace-production-persistence-spec.md` before implementing or +reviewing database-backed Workspace persistence. + ## Key Boundary VULCA reviews and controls creative judgment. It does not replace Figma, Canva, @@ -67,3 +77,4 @@ Agents can operate inside VULCA. Agents are not the product identity. Sources: - `source-index.md` Workspace section +- `15-workspace-production-persistence-spec.md` diff --git a/docs/review-context/14-release-readiness-evidence-gate.md b/docs/review-context/14-release-readiness-evidence-gate.md index 76799ea1..780b5b1e 100644 --- a/docs/review-context/14-release-readiness-evidence-gate.md +++ b/docs/review-context/14-release-readiness-evidence-gate.md @@ -47,6 +47,8 @@ As of the current vault state: `copy-gates/website-ppt-copy-gate.json`. - M5 closeout is recorded in `release-readiness/m5-closeout-summary.json`. +- Production Workspace persistence design is specified in + `15-workspace-production-persistence-spec.md`. - PPT proof lab remains public blocked by the latest remembered Run 2.93 gate. Still missing for product release readiness: @@ -106,6 +108,9 @@ Current evidence: - Platform PR #34 adds a shared in-process backend review-state API and frontend Workspace load/save mirroring, with backend-side `public_ready=false` locking. +- `15-workspace-production-persistence-spec.md` defines the product design for + database-backed storage, authorization, conflict handling, audit events, and + multi-instance behavior. Remaining boundary: @@ -344,6 +349,7 @@ Acceptance: - `docs/review-context/11-artifact-bridge-spec.md` - `docs/review-context/12-complete-demo-path.md` - `docs/review-context/13-website-ppt-claim-spine.md` +- `docs/review-context/15-workspace-production-persistence-spec.md` - `origin/master:docs/product/workspace-current-state-audit.md` - `docs/platform/release-readiness-status.md` - Platform Workspace baseline `6efef07 fix: align workspace context review controls` diff --git a/docs/review-context/15-workspace-production-persistence-spec.md b/docs/review-context/15-workspace-production-persistence-spec.md new file mode 100644 index 00000000..2c0d5a9d --- /dev/null +++ b/docs/review-context/15-workspace-production-persistence-spec.md @@ -0,0 +1,247 @@ +# Workspace Production Persistence Spec + +Vault status: protected product persistence spec. + +## Purpose + +This file defines the product design for production-grade Workspace +persistence. It turns the current Workspace preview and shared review-state +slice into a durable, multi-user Creative Repo product layer. + +This is a product spec, not only a backend implementation note. It defines what +must be saved, who may change it, how concurrent review work is resolved, and +which evidence is required before VULCA can claim product-level release +readiness. + +## Current Baseline + +The current platform state has three relevant merged slices: + +- PR #31 adds the Workspace review product shell. +- PR #32 adds local durable review state and release-owner audit trail + persistence. +- PR #34 adds a shared in-process backend review-state API at + `/api/v1/workspace/review-state/{repo_id}` and frontend Workspace load/save + mirroring. + +The baseline proves the product direction and a shared API surface. It does not +prove production persistence, authorization, conflict handling, or +multi-instance behavior. + +## Product Position + +Production persistence belongs to the Workspace / Creative Repo product layer. + +```text +VULCA Product + -> Workspace / Creative Repo + -> Review UI + -> EvidencePack / Artifact Bridge + -> Decision / ReleaseGate + -> Production Persistence and Collaboration Layer +``` + +The persistence layer is successful only if a reviewer can leave, reload, +switch device, or collaborate with another reviewer without losing review +items, evidence, decisions, blocker state, release gates, or audit history. + +## Non-Goals + +- Do not treat process memory as production storage. +- Do not let client-side normalization be the only release safety boundary. +- Do not let agents or system checks finalize public release. +- Do not use this spec to upgrade product-level R5 until implementation + evidence and a human release owner decision exist. +- Do not turn Workspace into a generic file drive or editor replacement. + +## Product Objects + +Production persistence must preserve these objects independently, not only as a +single opaque JSON blob: + +| Object | Product meaning | Persistence requirement | +| --- | --- | --- | +| `CreativeRepo` | One project source of truth | Durable repo identity, owner, status, timestamps | +| `Brief` | Business, visual, and cultural task | Versioned brief text and source references | +| `MotifBranch` | Creative direction under review | Branch identity, status, parent repo, versions | +| `VisualVariant` | Generated/imported candidate or version | Artifact refs, provenance, visible labels | +| `AgentRun` | Execution trace inside the repo | Tool name, model/provider, warnings, outputs | +| `EvidencePack` | Proof bundle for a decision | Source refs, checks, missing evidence, timestamps | +| `ReviewItem` | Unit of review work | Assignee, mode, status, selected artifact, blocker state | +| `Decision` | Human or advisory review decision | Actor, role, action, reason, revision | +| `ReleaseGate` | Product release boundary | Public release blocked unless human release owner clears it | +| `AuditEvent` | Durable history entry | Append-only actor, action, target, before/after revision | + +The compatibility snapshot can still exist for frontend convenience, but it +must be derived from these durable records. + +## Roles And Authorization + +Every persistence operation must resolve the actor and role before reading or +writing Workspace state. + +| Role | May read | May write | May release | +| --- | --- | --- | --- | +| `repo_owner` | Own repos | Repo metadata, members, archive state | No by default | +| `reviewer` | Assigned review items | Review decisions, comments, evidence notes | No | +| `release_owner` | Release queue and all evidence | Final release decision and gate notes | Yes, with audit | +| `agent` | Assigned execution context | AgentRun, advisory checks, evidence drafts | No | +| `system` | Operational metadata | migrations, derived indexes, health state | No | + +Authorization rules: + +- A user cannot read a repo without membership or owner access. +- A reviewer cannot change repo membership or release-owner status. +- An agent can append evidence and advisory checks, but cannot clear the + release gate. +- A release-owner action must create an append-only `AuditEvent`. +- Failed authorization must return a stable 403 response and must not mutate + state. + +## Persistence Architecture + +The production backend should store Workspace state in a database-backed model, +not process memory. + +Required storage properties: + +- database-backed state survives backend restart; +- state is shared across backend instances; +- write operations are atomic at the review item or repo revision boundary; +- audit events are append-only; +- artifact files are referenced by durable object storage paths, not embedded + in the review-state snapshot; +- each mutable aggregate has a revision number. + +Recommended aggregate boundaries: + +- `CreativeRepo` aggregate: repo metadata, members, current revision. +- `ReviewItem` aggregate: review status, selected variant, staged decision, + blocker state. +- `EvidencePack` aggregate: source refs, check outputs, missing evidence. +- `ReleaseGate` aggregate: current gate state and release-owner decision. +- `AuditEvent` stream: immutable change history across all aggregates. + +## API Contract + +The existing endpoint remains the compatibility route: + +```text +GET /api/v1/workspace/review-state/{repo_id} +PUT /api/v1/workspace/review-state/{repo_id} +DELETE /api/v1/workspace/review-state/{repo_id} +``` + +Production behavior changes: + +- `GET` returns a snapshot derived from durable database records. +- `PUT` validates actor permissions, checks revision, writes durable records, + and appends audit events. +- `DELETE` is test/admin-only outside production user flows. +- Every response includes the latest repo revision. + +New production routes should be added around explicit operations: + +```text +POST /api/v1/workspace/repos +GET /api/v1/workspace/repos/{repo_id} +POST /api/v1/workspace/repos/{repo_id}/review-items +PUT /api/v1/workspace/repos/{repo_id}/review-items/{item_id}/decision +POST /api/v1/workspace/repos/{repo_id}/evidence-packs +PUT /api/v1/workspace/repos/{repo_id}/release-gate +GET /api/v1/workspace/repos/{repo_id}/audit-events +``` + +The compatibility route can call these service-layer operations internally. + +## Conflict Model + +The production product must not silently overwrite another reviewer. + +Required behavior: + +- every mutable response includes `revision`; +- every write sends the base `revision`; +- stale writes return 409 with the latest revision and changed fields; +- frontend shows a conflict state instead of discarding local edits; +- non-overlapping evidence additions may be merged by the backend when the + service can prove the merge is safe; +- release-owner decisions never auto-merge. + +Minimum conflict policy: + +```text +if request.base_revision != current_revision: + reject with 409 + return current_revision + return changed_fields +else: + commit write + append audit event + increment revision +``` + +## Release-Gate Safety + +Release safety must be enforced in the backend service layer. + +Rules: + +- Stored release gates default to public blocked. +- Incoming client snapshots cannot upgrade release state without a + release-owner operation. +- AgentRun and system-derived checks may add advisory evidence only. +- Release-owner decisions must reference current EvidencePack revisions. +- A release-owner decision must include actor, role, timestamp, rationale, and + current repo revision. + +## Migration From Current Slice + +Migration from PR #34 should be staged: + +1. Keep the existing review-state endpoint as the frontend compatibility route. +2. Add database tables and service-layer operations behind the endpoint. +3. Store the current sample Workspace repo as seeded database data. +4. Convert frontend saves from whole-snapshot writes to operation-specific + writes. +5. Keep snapshot loading for initial page hydration until the UI reads specific + objects directly. +6. Add authorization and revision checks before any public demo uses shared + production data. + +## Acceptance Gates + +Production persistence is not accepted until these gates pass: + +- Backend unit tests prove release gate normalization and authorization. +- Backend integration tests prove database persistence across app restart. +- Multi-client tests prove two reviewers see the same committed state. +- Conflict tests prove stale writes return 409 without mutation. +- Multi-instance tests prove state is shared outside one process. +- Frontend tests prove conflict UI and sync failure behavior. +- E2E tests prove create, reload, update, decision, audit, and release-gate + flows through the database-backed API. +- A release-readiness report records the human release owner decision. + +## R-Level Effect + +This spec does not upgrade current release status by itself. + +- Current maximum from protected vault evidence remains R4, example-specific. +- Product-level R5 remains blocked. +- R5 can be reconsidered only after production persistence, artifact ingestion, + EvidencePack rendering, human release workflow, public example quality, and + website/PPT copy gates all have implementation evidence and a human release + owner decision. + +## Sources + +- `docs/review-context/07-workspace-product-model.md` +- `docs/review-context/11-artifact-bridge-spec.md` +- `docs/review-context/12-complete-demo-path.md` +- `docs/review-context/14-release-readiness-evidence-gate.md` +- `docs/review-context/workspace-durable/README.md` +- `docs/review-context/release-readiness/M5-CLOSEOUT.md` +- `yha9806/vulca-platform` PR #31. +- `yha9806/vulca-platform` PR #32. +- `yha9806/vulca-platform` PR #34. diff --git a/docs/review-context/CHANGELOG.md b/docs/review-context/CHANGELOG.md index ebe654b9..77397b32 100644 --- a/docs/review-context/CHANGELOG.md +++ b/docs/review-context/CHANGELOG.md @@ -4,6 +4,24 @@ Vault status: append-only change log. ## 2026-06-16 +### Added Workspace Production Persistence Spec + +- Added `15-workspace-production-persistence-spec.md` as the protected product + design for database-backed Workspace persistence, authorization, conflict + handling, audit history, and multi-instance behavior. +- Wired the spec into the README read order, manifest, validator, source index, + Workspace product model, durable review status, release-readiness gate, and + M5 closeout. +- Preserved the boundary that this spec does not upgrade product-level R5 + without implementation evidence and a human release owner decision. + +Source basis: + +- `docs/review-context/07-workspace-product-model.md`. +- `docs/review-context/14-release-readiness-evidence-gate.md`. +- `docs/review-context/release-readiness/M5-CLOSEOUT.md`. +- `yha9806/vulca-platform` PR #34. + ### Recorded Platform Shared Workspace Review-State Merge - Recorded platform PR #34 as merged to `master` with shared backend diff --git a/docs/review-context/MANIFEST.json b/docs/review-context/MANIFEST.json index efce0e15..ef9f2157 100644 --- a/docs/review-context/MANIFEST.json +++ b/docs/review-context/MANIFEST.json @@ -34,6 +34,7 @@ "12-complete-demo-path.md", "13-website-ppt-claim-spine.md", "14-release-readiness-evidence-gate.md", + "15-workspace-production-persistence-spec.md", "artifact-bridge/README.md", "artifact-bridge/m3-demo-bridge-fixture.json", "workspace-durable/README.md", @@ -64,6 +65,7 @@ "complete_demo_path": "12-complete-demo-path.md", "website_ppt_claim_spine": "13-website-ppt-claim-spine.md", "release_readiness_gate": "14-release-readiness-evidence-gate.md", + "workspace_production_persistence_spec": "15-workspace-production-persistence-spec.md", "release_readiness_report_template": "release-readiness/TEMPLATE.md", "m5_closeout_summary": "release-readiness/m5-closeout-summary.json", "website_film_led_homepage_branch": "5dc32cd", diff --git a/docs/review-context/README.md b/docs/review-context/README.md index 69d3fb95..56a03343 100644 --- a/docs/review-context/README.md +++ b/docs/review-context/README.md @@ -44,6 +44,8 @@ mainline and does not carry or require the vault validation gate. - `13-website-ppt-claim-spine.md`: shared website, README, PPT, and public story claim spine. - `14-release-readiness-evidence-gate.md`: M5 release-readiness evidence gate. +- `15-workspace-production-persistence-spec.md`: product spec for database, + authorization, conflict, audit, and multi-instance Workspace persistence. - `artifact-bridge/`: RR2 reference fixture for projecting SDK/MCP artifacts into Workspace review objects. - `workspace-durable/`: RR3 durable review fixture for reload-preserved @@ -82,8 +84,11 @@ mainline and does not carry or require the vault validation gate. positioning, public decks, or PPT proof-lab summaries. 13. Read `14-release-readiness-evidence-gate.md` before upgrading any preview, internal, public-blocked, or release-readiness status. -14. Use `release-readiness/TEMPLATE.md` before proposing a stronger release +14. Read `15-workspace-production-persistence-spec.md` before implementing or + reviewing production Workspace persistence, authorization, conflict + handling, audit history, or multi-instance behavior. +15. Use `release-readiness/TEMPLATE.md` before proposing a stronger release level, public example, website claim, or PPT claim. -15. Read `release-readiness/M5-CLOSEOUT.md` before summarizing current +16. Read `release-readiness/M5-CLOSEOUT.md` before summarizing current release-readiness state. -16. If this vault needs a change, create a request packet instead of editing it. +17. If this vault needs a change, create a request packet instead of editing it. diff --git a/docs/review-context/gates/validate_review_context.py b/docs/review-context/gates/validate_review_context.py index 4ac2d12c..2c48a0b9 100644 --- a/docs/review-context/gates/validate_review_context.py +++ b/docs/review-context/gates/validate_review_context.py @@ -45,6 +45,7 @@ "12-complete-demo-path.md", "13-website-ppt-claim-spine.md", "14-release-readiness-evidence-gate.md", + "15-workspace-production-persistence-spec.md", ] RELEASE_READINESS_TEMPLATE_REQUIRED_ITEMS = [ diff --git a/docs/review-context/release-readiness/M5-CLOSEOUT.md b/docs/review-context/release-readiness/M5-CLOSEOUT.md index d89949d2..c0fd5b93 100644 --- a/docs/review-context/release-readiness/M5-CLOSEOUT.md +++ b/docs/review-context/release-readiness/M5-CLOSEOUT.md @@ -42,6 +42,9 @@ As of 2026-06-16: These PRs improve R5 evidence, but they do not change the product-level decision above. +The next product-design reference for closing the persistence blocker is +`15-workspace-production-persistence-spec.md`. + ## Indexed Evidence - RR1 checklist/report template: @@ -56,6 +59,8 @@ decision above. `copy-gates/website-ppt-copy-gate.json` - Machine-readable closeout: `release-readiness/m5-closeout-summary.json` +- Production Workspace persistence spec: + `15-workspace-production-persistence-spec.md` ## Remaining R5 Blockers @@ -70,6 +75,7 @@ decision above. ## Sources - `docs/review-context/14-release-readiness-evidence-gate.md` +- `docs/review-context/15-workspace-production-persistence-spec.md` - `docs/review-context/release-readiness/TEMPLATE.md` - `docs/review-context/artifact-bridge/m3-demo-bridge-fixture.json` - `docs/review-context/workspace-durable/m3-durable-review-fixture.json` diff --git a/docs/review-context/release-readiness/m5-closeout-summary.json b/docs/review-context/release-readiness/m5-closeout-summary.json index c23d2348..953beb53 100644 --- a/docs/review-context/release-readiness/m5-closeout-summary.json +++ b/docs/review-context/release-readiness/m5-closeout-summary.json @@ -27,6 +27,11 @@ "status": "indexed", "source": "docs/review-context/workspace-durable/README.md" }, + { + "name": "Workspace production persistence product spec", + "status": "indexed", + "source": "docs/review-context/15-workspace-production-persistence-spec.md" + }, { "name": "EvidencePack rendering test report", "status": "indexed", diff --git a/docs/review-context/source-index.md b/docs/review-context/source-index.md index d3fa75a8..cf495d86 100644 --- a/docs/review-context/source-index.md +++ b/docs/review-context/source-index.md @@ -99,6 +99,10 @@ check before changing high-level VULCA claims. - Protected M5 release-readiness gate for Workspace persistence, artifact ingestion, evidence rendering, human release workflow, public examples, and website/PPT copy review. +- `docs/review-context/15-workspace-production-persistence-spec.md` + - Protected product spec for production Workspace database persistence, + authorization, conflict handling, audit history, and multi-instance + behavior. - `docs/review-context/release-readiness/TEMPLATE.md` - Protected RR1 report template for recording evidence links, reviewer/owner fields, Gate 1-6 status, and release decisions. @@ -149,6 +153,10 @@ check before changing high-level VULCA claims. - M5 closeout: - `docs/review-context/release-readiness/m5-closeout-summary.json` - Current release-readiness index and product-level release boundary. +- Workspace production persistence spec: + - `docs/review-context/15-workspace-production-persistence-spec.md` + - Product design for database-backed persistence, authorization, revision + conflicts, audit history, and multi-instance behavior. ## Workspace Product @@ -182,6 +190,10 @@ Workspace product code lives in the separate `vulca-platform` repository. - Merge commit: `d06a713bf490ad870fe9273f933c310e2955b4e9`. - Boundary: in-process shared backend state only; not production database-backed, authorized, conflict-safe, or multi-instance persistence. +- Production persistence design: + - `docs/review-context/15-workspace-production-persistence-spec.md`. + - This is the next product-layer design reference before changing the + platform database, permissions, conflict, or audit model. ## Website diff --git a/docs/review-context/workspace-durable/README.md b/docs/review-context/workspace-durable/README.md index 0215bdf4..750b4c0a 100644 --- a/docs/review-context/workspace-durable/README.md +++ b/docs/review-context/workspace-durable/README.md @@ -35,6 +35,9 @@ evidence, but they do not certify production persistence, authorization, conflict handling, multi-instance durability, or product-level release readiness. +Use `../15-workspace-production-persistence-spec.md` for the product design +that turns these slices into production database-backed persistence. + ## Current Fixtures - `m3-durable-review-fixture.json`: RR3 reference fixture showing the M3 @@ -55,6 +58,7 @@ readiness. - `docs/review-context/07-workspace-product-model.md` - `docs/review-context/12-complete-demo-path.md` - `docs/review-context/14-release-readiness-evidence-gate.md` +- `docs/review-context/15-workspace-production-persistence-spec.md` - `docs/review-context/artifact-bridge/m3-demo-bridge-fixture.json` - `yha9806/vulca-platform` PR #31. - `yha9806/vulca-platform` PR #32. diff --git a/tests/test_review_context_vault.py b/tests/test_review_context_vault.py index 57e6285d..f4c1614d 100644 --- a/tests/test_review_context_vault.py +++ b/tests/test_review_context_vault.py @@ -26,6 +26,7 @@ "12-complete-demo-path.md", "13-website-ppt-claim-spine.md", "14-release-readiness-evidence-gate.md", + "15-workspace-production-persistence-spec.md", ] REQUEST_TEMPLATE_CHECKS = [