1  # Collaboration Scenarios & Cherry-Pick Workflow Design
  2  
  3  ## Overview
  4  
  5  This document explores the collaboration patterns in InterBrain's cherry-pick workflow, from trivial (works out of box) to complex (requires AI magic glue). It serves as:
  6  
  7  1. **Conceptual script** for the Alice/Bob/Charlie/David test scenario
  8  2. **Design guide** for the DreamSong canvas collaboration
  9  3. **Scope definition** for private beta feature cutoff
 10  
 11  ## The Four-Person Test Scenario
 12  
 13  ### Cast
 14  - **Alice**: Creates original content that gets relayed through the network
 15  - **Bob**: Direct collaborator, relays Alice's work, adds own contributions
 16  - **Charlie**: Another collaborator, also relays Alice's work, adds own contributions
 17  - **David**: Our test perspective - receives commits from Bob and Charlie
 18  
 19  ### Timeline Script
 20  
 21  ```
 22  Day 1: Alice creates "Project Vision" DreamNode
 23  ├── Initial commit: README.md with project description
 24  └── Shares with Bob and Charlie
 25  
 26  Day 2: Bob works on the project
 27  ├── Commit B1: Adds his introduction to README.md
 28  ├── Commit B2: Creates RESOURCES.md (new file)
 29  └── Cherry-picks Alice's vision commit (now has provenance marker)
 30  
 31  Day 3: Charlie works on the project
 32  ├── Commit C1: Adds her introduction to README.md
 33  ├── Commit C2: Creates DESIGN-NOTES.md (new file)
 34  └── Cherry-picks Alice's vision commit (same content as Bob's cherry-pick)
 35  
 36  Day 4: David connects to Bob and Charlie
 37  ├── Sees Bob offering: B1, B2, Alice's-commit-via-Bob
 38  ├── Sees Charlie offering: C1, C2, Alice's-commit-via-Charlie
 39  └── Alice's commit is DEDUPLICATED (same originalHash)
 40  
 41  David's choices:
 42  ├── Accept Alice's commit (from either peer) ✓ trivial
 43  ├── Accept B2 (new file) ✓ trivial
 44  ├── Accept C2 (new file) ✓ trivial
 45  ├── Accept B1 (README edit) ✓ works if first
 46  ├── Accept C1 (README edit) ⚠️ CONFLICTS if B1 already applied
 47  └── Accept both B1 and C1 ⚠️ requires merge strategy
 48  ```
 49  
 50  ### Key Insight: Commit Independence
 51  
 52  The critical realization is that **commits from different peers that touch the same file are fundamentally parallel branches**. Git has no way to know that B1 and C1 are both "add a section to Contributors" - it just sees two different diffs against the same base.
 53  
 54  ---
 55  
 56  ## Collaboration Pattern Spectrum
 57  
 58  ### Level 1: Trivial (Works Out of Box)
 59  
 60  **Pattern: Adding new files**
 61  - Each commit creates a new file
 62  - No conflicts possible
 63  - Cherry-pick always succeeds
 64  
 65  **Examples:**
 66  - Adding photos to a shared album
 67  - Adding documents to a research collection
 68  - Adding resource links as separate markdown files
 69  
 70  **User guidance:** "To contribute, drag and drop files onto the DreamNode"
 71  
 72  **Private beta scope:** ✅ Fully supported
 73  
 74  ---
 75  
 76  ### Level 2: Simple (Works with ordering)
 77  
 78  **Pattern: Sequential edits to same file from same peer**
 79  - Commits form a linear chain
 80  - Cherry-pick in order always works
 81  - Cherry-pick out of order may conflict
 82  
 83  **Examples:**
 84  - Bob makes edit 1, then edit 2, then edit 3
 85  - David cherry-picks all three in order
 86  
 87  **User guidance:** "Accept all commits from a peer together"
 88  
 89  **Private beta scope:** ✅ Supported (UI encourages accepting all from peer)
 90  
 91  ---
 92  
 93  ### Level 3: Moderate (Works with smart merging)
 94  
 95  **Pattern: Edits to different sections of same file**
 96  - Two peers edit different parts of a file
 97  - Git's merge strategies *might* handle this
 98  - Depends on how "far apart" the edits are
 99  
100  **Git options to explore:**
101  ```bash
102  # Try recursive merge strategy during cherry-pick
103  git cherry-pick -X theirs <commit>  # Accept incoming for conflicts
104  git cherry-pick -X ours <commit>    # Keep current for conflicts
105  
106  # Three-way merge with specific strategy
107  git cherry-pick --strategy=recursive -X patience <commit>
108  ```
109  
110  **Examples:**
111  - Bob adds section at top of README
112  - Charlie adds section at bottom of README
113  - *Might* merge cleanly if git can identify the regions
114  
115  **Private beta scope:** ⚠️ Partial - works sometimes, conflicts sometimes
116  
117  ---
118  
119  ### Level 4: Complex (Requires AI Magic Glue)
120  
121  **Pattern: Edits to same section of same file**
122  - Two peers both edit the Contributors section
123  - Git cannot resolve - sees conflicting changes
124  - Semantically, both additions are valid
125  
126  **The Magic Glue Opportunity:**
127  
128  ```
129  Before AI glue:
130  <<<<<<< HEAD
131  ### Bob
132  Bob's introduction...
133  =======
134  ### Charlie
135  Charlie's introduction...
136  >>>>>>> incoming
137  
138  After AI glue (semantic merge):
139  ### Bob
140  Bob's introduction...
141  
142  ### Charlie
143  Charlie's introduction...
144  ```
145  
146  The LLM understands the *intent* is "add a contributor section" and can merge both.
147  
148  **Private beta scope:** ❌ Not in initial scope, but designed for future
149  
150  ---
151  
152  ## DreamSong Canvas Collaboration
153  
154  ### Canvas File Structure
155  
156  The `.canvas` file is JSON:
157  ```json
158  {
159    "nodes": [
160      { "id": "abc123", "type": "text", "x": 100, "y": 200, "text": "..." },
161      { "id": "def456", "type": "file", "x": 300, "y": 200, "file": "image.png" }
162    ],
163    "edges": [
164      { "id": "edge1", "fromNode": "abc123", "toNode": "def456" }
165    ]
166  }
167  ```
168  
169  ### Canvas Collaboration Patterns
170  
171  #### Level 1: Adding new nodes (Trivial... mostly)
172  
173  **The challenge:** Even adding a new node modifies the same `.canvas` file.
174  
175  **However:** If nodes have unique IDs and are appended to arrays, a smart merge *could* work.
176  
177  **Potential solution: Canvas-aware merge driver**
178  ```bash
179  # .gitattributes
180  *.canvas merge=canvas-merge
181  ```
182  
183  A custom merge driver that understands canvas structure:
184  - Merge `nodes` arrays (combine unique IDs)
185  - Merge `edges` arrays (combine unique IDs)
186  - Conflict only on same-ID modifications
187  
188  **Private beta scope:** 🔬 Worth exploring - could unlock huge value
189  
190  #### Level 2: Editing existing nodes
191  
192  **The challenge:** Two people edit the same text node.
193  
194  **Git sees:** Conflicting changes to the same JSON object.
195  
196  **AI glue opportunity:** Semantic text merging within the node.
197  
198  **Private beta scope:** ❌ Complex, defer to later
199  
200  #### Level 3: Restructuring/moving nodes
201  
202  **The challenge:** Spatial layout is meaningful in canvas.
203  
204  **Git sees:** Changed x/y coordinates as conflicts.
205  
206  **AI glue opportunity:** Layout reconciliation.
207  
208  **Private beta scope:** ❌ Very complex, defer to later
209  
210  ---
211  
212  ## Recommended Private Beta Scope
213  
214  ### Fully Supported
215  1. **New file contributions** - drag & drop files
216  2. **Sequential commits from same peer** - accept all together
217  3. **Deduplication of relayed commits** - same originalHash
218  
219  ### Partially Supported (with warnings)
220  4. **Parallel README edits** - warn user of potential conflict
221  5. **Canvas node additions** - explore custom merge driver
222  
223  ### Deferred (designed for, not implemented)
224  6. **AI magic glue for conflicts** - architecture ready, not active
225  7. **Semantic canvas merging** - future feature
226  8. **Complex multi-peer edit reconciliation** - future feature
227  
228  ---
229  
230  ## Technical Approaches to Explore
231  
232  ### 1. Git Merge Strategies for Cherry-Pick
233  
234  ```typescript
235  // Try cherry-pick with different strategies
236  async function smartCherryPick(hash: string): Promise<CherryPickResult> {
237    // First try: standard cherry-pick
238    try {
239      await exec(`git cherry-pick -x ${hash}`);
240      return { success: true, strategy: 'standard' };
241    } catch (e) {
242      await exec('git cherry-pick --abort');
243    }
244  
245    // Second try: with patience algorithm (better for additions)
246    try {
247      await exec(`git cherry-pick -x -X patience ${hash}`);
248      return { success: true, strategy: 'patience' };
249    } catch (e) {
250      await exec('git cherry-pick --abort');
251    }
252  
253    // Third try: accept theirs for conflicts (if user approves)
254    // This loses local changes in conflict regions
255  
256    return { success: false, needsManualMerge: true };
257  }
258  ```
259  
260  ### 2. Canvas-Aware Merge Driver
261  
262  ```typescript
263  // Custom merge for .canvas files
264  function mergeCanvasFiles(base: Canvas, ours: Canvas, theirs: Canvas): Canvas {
265    return {
266      nodes: mergeArraysById(base.nodes, ours.nodes, theirs.nodes),
267      edges: mergeArraysById(base.edges, ours.edges, theirs.edges)
268    };
269  }
270  
271  function mergeArraysById<T extends {id: string}>(
272    base: T[], ours: T[], theirs: T[]
273  ): T[] {
274    const result = new Map<string, T>();
275  
276    // Start with base
277    base.forEach(item => result.set(item.id, item));
278  
279    // Apply ours
280    ours.forEach(item => result.set(item.id, item));
281  
282    // Apply theirs (new items only, or flag conflicts)
283    theirs.forEach(item => {
284      if (!result.has(item.id)) {
285        result.set(item.id, item);
286      } else if (JSON.stringify(result.get(item.id)) !== JSON.stringify(item)) {
287        // Same ID, different content = conflict
288        // For now: theirs wins for new additions, ours wins for modifications
289      }
290    });
291  
292    return Array.from(result.values());
293  }
294  ```
295  
296  ### 3. Conflict Detection Before Preview
297  
298  ```typescript
299  // Check if cherry-pick would conflict BEFORE showing preview
300  async function wouldConflict(hash: string): Promise<boolean> {
301    try {
302      // Dry-run cherry-pick
303      await exec(`git cherry-pick --no-commit ${hash}`);
304      await exec('git reset --hard HEAD');
305      return false;
306    } catch (e) {
307      await exec('git cherry-pick --abort').catch(() => {});
308      return true;
309    }
310  }
311  ```
312  
313  ---
314  
315  ## User Guidance for Smooth Collaboration
316  
317  ### Do's
318  - Add new files rather than editing shared files
319  - Make small, focused commits with clear messages
320  - Accept all commits from a peer together (preserves their chain)
321  - Use the preview feature before accepting
322  
323  ### Don'ts
324  - Edit the same section another collaborator is working on
325  - Cherry-pick commits out of order from the same peer
326  - Make large commits that touch many files
327  
328  ### UI Guardrails
329  - Group commits by peer (done ✅)
330  - "Accept All" button per peer (done ✅)
331  - Conflict warning before cherry-pick (to implement)
332  - Suggest "New File" pattern for contributions (to implement)
333  
334  ---
335  
336  ## Next Steps
337  
338  1. **Fix test scenario** to follow the realistic timeline above
339  2. **Implement conflict detection** before preview
340  3. **Explore canvas merge driver** as high-value unlock
341  4. **Design AI glue architecture** for future conflict resolution