Engineering Standards: Repository Consolidation Standard¶

This document defines the standard operating procedure (SOP) for repository branch consolidation. It ensures that divergent development lineages are merged cleanly, no work is lost, changes are semantically verified, and the history is cleanly resolved for long-term auditing.

Phase 1: Audit¶

Refresh Metadata: Fetch all remote branch changes to ensure the local state is fully current:
```
git fetch --all --prune
```
Analyze Divergence: List all remote branches and audit which commits are not represented in the integration/target branch:
```
git branch -r --no-merged <integration-branch>
```
Trace Roots: Check if divergent branches share a common history. If there is no common ancestor, prepare to merge with --allow-unrelated-histories.
Identify Duplicate History: Distinguish rebased/cherry-picked commits from true unique work by running comparative logs.

Phase 2: Integration¶

Merge Base Lineages: Merge major release or trunk lineages first, resolving conflicts in favor of the canonical/live-site config state:
```
git merge --allow-unrelated-histories <branch>
```
Audit Feature Branches (Chronological Keep/Skip):
Generate an audit checklist of all unique commits on the feature branch.
Classify each commit as KEEP (platform, core features, infrastructure) or SKIP (unrelated projects, temporary credentials, social media code).
Cherry-pick only the KEEP commits in chronological order (oldest first).
Resolve Conflicts Safely:
System / Configuration Files: If conflicts occur in files that represent canonical target-branch configuration (such as composer.json, .gitignore, .gitlab-ci.yml, or config/sync/*), resolve them by checking out our version (git checkout --ours).
Retired Codebases: If modify/delete conflicts occur on retired directories (e.g., archived Next.js code), resolve them by keeping them deleted (git rm <file>).
Functional Changes: Stop and manually inspect code conflicts in active business logic.
Close History for Re-represented Branches: For branches whose patches were already incorporated or cherry-picked, execute a merge using the ours strategy to cleanly close their timelines in the Git graph:
```
git merge -s ours <stale-branch>
```

Phase 3: Verification¶

Verify Tips Alignment: All aligned target branches (main, release/v0.1.x, refactor/local-source-override) must resolve to the exact same SHA:
```
git rev-parse origin/main
git rev-parse origin/release/v0.1.x
git rev-parse origin/refactor/local-source-override
```
Verify Tree Equality: Confirm that diffs between target branches are completely empty:
```
git diff <branch-1>..<branch-2>
```
Verify No Outstanding Branches: Ensure that git branch -r --no-merged returns empty.
Verify Internal Consistency: Run a complete integrity check on the repository database:
```
git fsck --full
```

Phase 4: Evidence¶

Generate a permanent, self-contained consolidation receipt (like consolidation_receipt.md) documenting: 1. Repository Metadata: Repository name, verified commits, and date. 2. Objective Evidence: Command logs demonstrating tips alignment, empty diffs, and clean fsck results. 3. Semantic Equivalence Proofs: Verification of matching git patch-id values for re-represented commits. 4. Architectural Decisions: Citations of project files/tasks justifying retired/deleted code blocks. 5. Discarded Changes Inventory: Log of which configuration files were overridden with ours and why. 6. Limitations: Declarations of the boundary of the verification.

Phase 5: Release¶

Establish a Permanent Checkpoint: Tag the final consolidation commit to prevent accidental loss:
```
git tag consolidation-YYYY-MM-DD
```
Safely Realignment Target Branches: Realign target branches locally using git reset --hard and push them using git push --force-with-lease to rewrite protected pointers safely.
Establish Protection Rules: Configure branch protection rules on GitLab/GitHub to prevent further force-pushes.