Merge Generation
Need User FeedbackWhen diverged branches need to be merged, REAP runs a specialized 6-stage lifecycle called Merge Generation — separate from the normal generation lifecycle. The core principle: align the genome first, then merge source code.
Why is Merge Generation different from a regular git merge?
A regular git merge only resolves source code conflicts. But when two branches evolve independently — each with their own generations, genome changes, and design decisions — merging source code alone isn't enough. The genome (architecture principles, conventions, constraints, business rules) may have diverged too. Merge Generation adds three critical steps before the source merge: detecting genome divergence, mating (resolving genome conflicts), and verifying genome-source consistency after the merge. This ensures that the merged codebase isn't just compile-clean, but also design-consistent.
Source conflicts → resolve → commit. Design consistency is not checked. Semantic conflicts go undetected.
Genome align first → source merge guided by genome → verify genome-source consistency → validate → commit. Invisible semantic conflicts are caught.
Why genome alignment comes first
Resolving source code conflicts does not guarantee the absence of semantic conflicts. Two pieces of code can merge cleanly — no git conflicts at all — yet contradict each other in intent, architecture, or business logic. Only genome-based reasoning can detect these invisible conflicts: does the merged code still follow the architecture principles? Are the conventions consistent? Do the business rules align? This is why REAP aligns the genome before touching source code. Once the genome is settled, it becomes the authoritative guide for resolving source conflicts — not just syntactically, but semantically.
Stage Order
| Stage | What happens | Artifact |
|---|---|---|
| Detect | Scan the target branch via git refs. Find the common ancestor using DAG BFS. Extract genome diffs. Classify conflicts as WRITE-WRITE or CROSS-FILE. | 01-detect.md |
| Mate | Present all genome conflicts to the human. For WRITE-WRITE: choose A, B, or merge manually. For CROSS-FILE: check logical compatibility. The genome must be fully resolved before proceeding. | 02-mate.md |
| Merge | Run git merge --no-commit with the target branch. Resolve any source conflicts guided by the finalized genome. Check for semantic conflicts — code that compiles but contradicts the genome. | 03-merge.md |
| Reconcile | Verify genome-source consistency after merge. AI compares genome and source code. User confirms any inconsistencies found. If issues exist, regress to Merge or Mate. | 04-reconcile.md |
| Validation | Run all mechanical testing commands (test, lint, build, type check). If any fail, regress to Merge or Mate. | 05-validation.md |
| Completion | Commit the merged result. Record the merge in meta.yml with type: merge and both parents. Archive to lineage. | 06-completion.md |
Conflict Types
| Type | Description | Resolution |
|---|---|---|
| WRITE-WRITE | Same genome file modified on both branches | Human decides: keep A, keep B, or merge |
| CROSS-FILE | Different genome files modified, but both branches changed genome | Human reviews for logical compatibility |
| Source conflict | Git merge conflict in source code | Resolved guided by finalized genome |
| Semantic conflict | Code merges cleanly but contradicts the genome (architecture, conventions, business rules) | Detected in Reconcile stage — AI compares genome and source, user confirms resolution |
| No conflict | No genome or source conflicts | Proceeds automatically |
Merge Regression
Validation or Reconcile failure can regress to Merge or Mate. Merge can regress to Mate if a genome issue is discovered. Regression rules follow the same pattern as normal generations — reason recorded in timeline and artifact.