
## 1. Rolling Back a Fork

If your senior devs (Claude Code or Antigravity) pull in an upstream update that breaks your modular architecture or conflicts with your security layers, you have two main ways to "undo" it:

* **The "Undo" (Git Reset):** You can force the codebase to jump back to exactly how it looked five minutes (or five days) ago. It effectively deletes the "bad" update from your history.
* **The "Revert" (Git Revert):** This creates a *new* update that specifically undoes the changes of the *bad* update. This is safer because it keeps a record of what went wrong.

---

## 2. Having "Two Copies" (Branching)

In Git, you don't usually need two separate folders on your computer to have two copies of the code. Instead, you use **Branches**.

Think of branches like parallel universes for your Agent-Native OS:

* **`main` branch:** This is your stable, production-ready OS.
* **`upstream-sync` branch:** You pull the latest weekly updates here first. You test them, see if they break your "Agentguard" layers, and only if they pass, do you merge them into `main`.
* **`experimental-modular` branch:** Where you try out a new "swap" for a layer without risking the stable core.

### Why this is better than two folders:

1. **Storage:** It’s much more efficient; Git only stores the *differences* between the copies.
2. **Comparison:** You can instantly "diff" (compare) the two copies to see exactly which line of code changed in the new update.
3. **Context Switching:** Your AI devs can swap between these "universes" in seconds with a single command.

---

## 3. The "Vendor Branch" Strategy

Since you are the Architect, you might want to direct your AI devs to use a **Vendor Branch** strategy.

1. Keep one branch that is a **pure mirror** of the original project (no custom code).
2. Keep your **custom product** on a separate branch.
3. When a new update comes out, you update the mirror first.
4. Then, tell Claude Code to "merge" the mirror into your custom branch. If it breaks, you just throw away that merge attempt and stay on your previous version until the AI can fix the conflict.

---

🛠️ Protocol: "Safe-Sync" Upstream Update
Role: Senior Developer (Claude Code) Objective: Synchronize the local repository with the original upstream while preserving the custom Agent-Native OS modular architecture. Constraint: Never perform a merge or rebase on the main branch directly.

Phase 1: Pre-Sync Safeguard (The "Black Box" Backup)
Before fetching any external code, create a permanent "snapshot" of the current stable state.

Identify the current state: Use git rev-parse --short HEAD to get the current commit ID.

Create a Backup Branch: * Name format: backup/pre-sync-[YYYY-MM-DD]

Command: git branch backup/pre-sync-$(date +%F)

Verify Clean Slate: Ensure all local changes are committed or stashed before proceeding.

Phase 2: The "Sandbox" Sync
Perform the synchronization in a temporary environment to evaluate impact.

Fetch Upstream: Retrieve the latest metadata from the original source.

git fetch upstream

Create a Sync Branch: Create a branch specifically for the merge.

git checkout -b feature/sync-upstream-$(date +%F)

Attempt the Merge: * git merge upstream/main (or the relevant primary branch).

Phase 3: Conflict & Architecture Audit
If the merge is successful, or if there are conflicts:

Conflict Resolution: If conflicts occur in the infra or Agentguard layers, stop. Notify the Architect if the original project has made structural changes that break our "swap/upgrade" modularity principle.

Regression Check: Run the existing test suite to ensure the "Main Chassis" remains stable.

Final Merge: Only after a successful audit, merge the feature/sync-upstream branch into main.

----
💡 Architect’s Pro-Tips for Your AI Devs
The "Point of No Return" Rule: If a merge conflict requires more than 10 lines of manual code alteration in a core security file, the AI should abort the merge (git merge --abort) and present a summary of the architectural clash to you.

Keep Your Folders Clean: Encourage your devs to keep custom Agent-Native logic in distinct directories (e.g., /src/custom_modules/) rather than editing the original project's files. This makes the "Safety First" sync much smoother because Git is smart enough to ignore files that don't exist in the upstream.