Git Merge

Git Merge Conflict Resolver for AI-DLC Projects

Resolve git merge conflicts that arise when multiple developers work on different AI-DLC units in parallel during the CONSTRUCTION phase.

When This Happens

After INCEPTION phase completes, the project is split into units. Multiple developers clone the repo and each runs CONSTRUCTION on their assigned unit. When they push/merge back:

1. State file conflicts — aidlc-docs/aidlc-state.md and aidlc-docs/audit.md are modified by every developer since each tracks their own unit's progress 2. Code conflicts — shared/common units modified by one developer conflict with another developer's changes or dependencies on that shared code

Conflict Resolution Workflow

Step 1: Detect and Classify Conflicts

Run git status to identify conflicted files, then classify each:

git diff --name-only --diff-filter=U

Classify each conflicted file into:

• State file — matches aidlc-docs/aidlc-state.md or aidlc-docs/audit.md
• Code file — everything else (application code, config, infrastructure)

Step 2: Resolve State File Conflicts

Read references/state-file-merge.md for the detailed merge strategy.

State files are logically non-conflicting — each developer wrote about their own unit. The strategy is:

• aidlc-state.md — merge unit progress sections, preserving both sides' checkbox states
• audit.md — combine entries chronologically by timestamp

These can be resolved automatically without user confirmation.

Step 3: Resolve Code Conflicts

Read references/code-conflict-merge.md for the detailed analysis strategy.

Code conflicts require understanding intent. For each conflicted code file: 1. Read the conflict markers to understand both sides 2. Load relevant design artifacts from aidlc-docs/construction/{unit-name}/ for context 3. Determine if changes are independent (both can coexist) or truly conflicting (one must win) 4. Present the analysis and proposed resolution to the user 5. Apply only after user approval

Step 4: Verify and Complete

After all conflicts are resolved:

git diff --name-only --diff-filter=U

Confirm zero remaining conflicts, then inform the user the merge is ready to commit.

Code Conflict Merge Strategy

Overview

Code conflicts occur when a shared/common unit's code is modified while other developers depend on or extend it. Unlike state files, these require semantic understanding.

Analysis Process

For each conflicted code file:

1. Read the Conflict

Parse the file and extract conflict regions:

• <<<<<<< HEAD (ours) — changes from the current branch
• ======= — separator
• >>>>>>> {branch} (theirs) — changes from the incoming branch

2. Identify Which Units Are Involved

Determine which unit(s) each side of the conflict belongs to:

• Check git log for the commits that touched this file
• Cross-reference with aidlc-docs/construction/plans/ to find which unit's code generation plan includes this file
• If the file is in a shared/common unit, identify which dependent units are affected

3. Load Design Context

Read the relevant design artifacts to understand intent:

• aidlc-docs/construction/{unit-name}/functional-design/ — business logic intent
• aidlc-docs/construction/{unit-name}/code/ — code generation summary
• aidlc-docs/construction/plans/{unit-name}-code-generation-plan.md — what was planned

4. Classify the Conflict

Additive (both can coexist):

• New methods/functions added by different units to the same file
• New imports added by both sides
• New configuration entries

→ Resolution: include both changes. Order logically (e.g., alphabetical imports, grouped methods).

Overlapping modification:

• Same function/method modified by both sides
• Same configuration value changed differently
• Same interface/contract changed incompatibly

→ Resolution: requires user decision. Present both versions with context from design artifacts.

Dependency conflict:

• Shared unit's API changed, breaking a dependent unit's usage
• Shared type/model modified, affecting consumers

→ Resolution: the shared unit's change is typically authoritative. Adapt the dependent unit's code to match. Present to user for confirmation.

5. Present Resolution

For each conflict, show the user:

## Conflict: {file-path}

**Type**: {Additive | Overlapping | Dependency}
**Units involved**: {unit-a}, {unit-b}

### Ours (HEAD):
{code from our side}

### Theirs ({branch}):
{code from their side}

### Proposed resolution:
{merged code}

### Rationale:
{why this resolution, referencing design artifacts}

Wait for user approval before applying.

Common Patterns

Shared model/type changes

When a shared data model is extended by multiple units:

• If both add new fields → merge both fields
• If both modify the same field → flag for user review
• Check domain-entities.md from both units for intent

API endpoint additions

When multiple units add endpoints to the same router/controller:

• Typically additive — include all endpoints
• Check for route conflicts (same path, different handlers)

Configuration file changes

When package.json, pom.xml, build.gradle, etc. conflict:

• Dependencies: union of both sides, flag version conflicts
• Scripts/tasks: include both, flag name collisions
• Settings: flag any differing values for user review

Infrastructure code (CDK/CloudFormation)

When infrastructure definitions conflict:

• New resources from different units → additive, include both
• Same resource modified → flag for user review, reference infrastructure-design.md
• Stack dependencies changed → careful review needed

State File Merge Strategy

aidlc-state.md

This file tracks stage progress per unit. In multi-user scenarios, each developer checks off their own unit's stages.

Merge Logic

1. Parse both sides (ours and theirs) of the conflict 2. Identify unit-specific sections — look for unit names under ### 🟢 CONSTRUCTION PHASE or per-unit stage entries 3. For each unit's checkbox lines (- [x] or - [ ]):

• If one side has [x] and the other has [ ] for the same line → use [x] (progress only moves forward)
• If both sides have [x] → keep [x]
• If both sides have [ ] → keep [ ]

4. For ## Current Status section — use the most recent timestamp and update the current stage to reflect combined progress 5. For ## Extension Configuration — should be identical on both sides (set during INCEPTION). If different, flag for user review

Conflict Marker Pattern

<<<<<<< HEAD
- [x] Code Generation - COMPLETE (unit-a)
=======
- [x] Code Generation - COMPLETE (unit-b)
>>>>>>> branch

Resolution: keep both lines — they describe different units.

Edge Cases

• Same unit modified by two developers — this shouldn't happen in normal workflow (units are assigned to individuals). Flag for user review.
• Project-level fields changed (Project Type, Start Date) — use HEAD version, these shouldn't change during CONSTRUCTION.

audit.md

This file is an append-only log of all interactions with timestamps.

Merge Logic

1. Extract all log entries from both sides — each entry is delimited by --- separators 2. Parse the **Timestamp**: field from each entry (ISO 8601 format) 3. Deduplicate — if identical entries exist on both sides (same timestamp + same content), keep one copy 4. Sort all entries chronologically by timestamp 5. Write the merged result

Conflict Marker Pattern

Typically the conflict spans large sections since both developers appended to the end of the file. Resolution: extract entries from both sides, sort by timestamp, concatenate.

Edge Cases

• Missing timestamps — place entries without timestamps at the end, grouped by which branch they came from
• Identical timestamps — preserve both entries, order by branch (HEAD first, then theirs)