Update / Versioning Protocol

Lifecycle of a UI surface

1. Idea — recorded as a manifest row (status: idea).
2. Cowork sketch — human/Cowork draft in Google Drive; flip cowork_sketch.
3. Spec in KB — agent writes knowledge/dev/ui/<surface>/spec.md; flip spec_in_kb, status → spec_ready.
4. Preview deploy — agent deploys /ui-preview/<project>/<surface>/vN/; flip preview_deployed, set preview_url + current_version, status → preview_deployed/needs_review.
5. Review — GPT review flips gpt_reviewed; User approval flips user_approved (status → approved). Recorded in the surface review-log. No self-approval.
6. Design polish → design_polish; code ready → code_ready; shell implemented → implemented.

After each step the agent updates the surface's own review-log and the master manifest.json.

How previews are versioned

• Each preview is immutable per version: /ui-preview/<project>/<surface>/vN/.
• A new look or contract = a new vN+1; the old version stays for comparison (as mow/unified-canvas/v1 + v2 already demonstrate). Never overwrite an existing preview.

How the master index is versioned (decision)

Decision for v1: keep versioned snapshots _master/v1, _master/v2, …

• Additive content updates (new surface row, status/checklist change) → redeploy manifest.json in place under _master/v1/. index.html is data-driven, so content changes need no code change. This is the common, low-risk path.
• Structural/layout changes (new columns, new filters, redesign) → cut _master/v2/.
• _master/current/ mutable pointer — recommended only if a single stable URL is later required. NOT created in v1 (avoids an unversioned mutable surface). If introduced, it must be an explicit copy of a chosen vN and documented in this protocol + the review-log.

Rationale: manifest is the moving part and is safe to refresh in place; the page shell is stable and benefits from immutable version snapshots, matching the existing preview convention.

Who does what

• Cowork: sketches, Drive references, raises new surfaces.
• Claude Code: deploys static previews + master index, keeps manifest/review-logs current.
• Claude Design: visual specs + design polish.
• GPT / User: review and approval (the only path to user_approved).