Architecture: How should platform generations, user manual edits, and vers...

Documentation for Sessions

🏗️ Architecture: How should platform generations, user manual edits, and vers...

Date: 2026-03-18
Time: 00:00:47 UTC
Session: gspace1-231.7
Agent: architecture
Confidence: 96%
Status: ✅ Documented

📋 Decision Context

Question:

How should platform generations, user manual edits, and version history coexist in the Git-backed platform builder?

Task: Design the e2e platform versioning, branching, and drafting system

🎯 Decision Made

Chosen:

Option C: Separate concerns via branch types. develop = sacred (only activated generations + published drafts). feature/generation-{ts} = immutable AI snapshots. draft/edit-{universe}-{ts} = user manual work. Activation = explicit user action. Unlimited drafts per universe, exactly one active generation. Validated by industry patterns: GitHub Copilot (copilot/ branches + draft PRs + human merge), Replit (Agent Checkpoints as immutable snapshots + separate File History for edits), Martin Fowler (trunk-based development with mainline as stable).

Options Considered:

  1. A: Discard manual edits on generation activation (too destructive)
  2. B: Auto-rebase manual edits onto new generation (too risky, nobody does this)
  3. C: Separate branch types with explicit activation (chosen, industry-validated)

💭 Reasoning

Three options evaluated: (A) Discard edits on activation — kills user iteration work, only Lovable does this and their users rarely do serious manual editing. (B) Rebase edits onto new generation — nobody in the industry does this automatically, conflict-prone, can silently corrupt work. (C) Separate branches — matches GitHub Copilot's validated copilot/ pattern, matches Replit's three-layer tracking, matches Fowler's mainline principle. The core insight: AI-generated code and human-edited code are fundamentally different artifacts with different lifecycles. Treating them as the same (on the same branch) creates irreconcilable merge conflicts. GitHub's approach is the most rigorous: the agent can ONLY write to copilot/ branches, draft PRs must be reviewed by a human who didn't request the generation, and the agent can never approve or merge its own PRs. This validates the explicit activation gate for non-first generations.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation