> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cross-Repo Sync Policy

> Version: 1.1.0 Last Updated: 2026-05-15 Status: Active

**Version:** 1.1.0
**Last Updated:** 2026-05-15
**Status:** Active

## Purpose

Define a single-source-of-truth branch model for:

* `origin` (`Encore-OS/encoreos`)
* `encore_lovable` (`Encore-OS/encoreos-87a1bffc`)

This policy prevents bidirectional merge loops and reduces production conflict risk.

## Canonical Source

* Canonical remote: `origin`
* Canonical long-lived branches:
  * `origin/development`
  * `origin/production`

`encore_lovable` is a **mirror target** for `development` only — it is never a commit source.

## Allowed Flow

1. Land feature work into `origin/development` via PR (from both IDE tooling and Lovable-sourced branches).
2. After CI success on `origin/development`, this workflow auto-mirrors to `encore_lovable/development`.
3. Promote to production from `origin` only.

```
origin/development (canonical)
        │
        │  [CI: mirror-development-to-encore-lovable.yml]
        ▼
encore_lovable/development (mirror, read-target for Lovable)
```

## Disallowed Flow

* No merging `encore_lovable/*` back into `origin/*` without cherry-pick review via a PR.
* No cherry-pick ping-pong between `origin` and `encore_lovable`.
* No direct push to `encore_lovable/development` for non-emergency purposes.
* No production PRs sourced from branches that contain `encore_lovable`-only history.

## Mirror Automation

**Workflow:** `.github/workflows/mirror-development-to-encore-lovable.yml`

Required repository secret:

* `ENCORE_LOVABLE_MIRROR_PAT`: fine-grained PAT with push access to `Encore-OS/encoreos-87a1bffc`.

Behavior:

* Triggered on push to `development`.
* Fetches `encore_lovable/development` and **counts commits not on `origin`**.
* If `encore_lovable` has diverged (unique commits), the workflow **fails immediately** with remediation steps in the job summary.
* If in-sync or origin-ahead: fast-forward pushes `origin/development` → `encore_lovable/development`.
* Non-FF push is not attempted automatically; force operations require explicit manual step.

## Developer Mirror Commands

| Command                           | Effect                                                                            |
| --------------------------------- | --------------------------------------------------------------------------------- |
| `npm run sync:mirror:status`      | Dry-run: fetch and report status, no push                                         |
| `npm run sync:mirror`             | Normal mirror: push origin → encore\_lovable (fails fast on divergence)           |
| `npm run sync:mirror:force-reset` | **DESTRUCTIVE**: reset encore\_lovable to origin state (prompts for confirmation) |

Legacy aliases `sync:dev`, `sync:dev:status`, `sync:lovable`, `sync:lovable:status` still work.

## Manual Recovery Procedure

If `encore_lovable/development` has diverged:

### Step 1 — Inspect the divergence

```bash theme={null}
git fetch origin encore_lovable
git log --oneline --left-right --graph \
    origin/development...encore_lovable/development
```

### Step 2A — Preserve Lovable-only commits (recommended)

1. Identify commits that should be preserved.
2. Create a branch off `origin/development`:
   ```bash theme={null}
   git checkout -b chore/recover-lovable-commits origin/development
   git cherry-pick <sha> [<sha> ...]
   ```
3. Open a PR to `origin/development`, get CI green, merge.
4. Re-run the mirror: `npm run sync:mirror`

### Step 2B — Discard Lovable-only commits

Only use this when the commits on `encore_lovable` are confirmed as disposable (e.g., Lovable experimentation not worth preserving):

```bash theme={null}
npm run sync:mirror:force-reset
# or: bash scripts/sync-lovable.sh --force-reset
```

This force-pushes `origin/development` to `encore_lovable/development`. Requires typing `yes` at the prompt.

### Step 3 — Confirm both remotes are in sync

```bash theme={null}
npm run sync:mirror:status
```

Both SHAs should match; the status log will confirm `IN SYNC`.

## Production Release Rule

Production merges must satisfy all:

* Branch source is canonical `origin` history only.
* Required CI checks are green.
* Branch divergence is reviewed.
* No unresolved merge conflicts.
* `encore_lovable` is in sync or cleanly behind `origin` (no unique commits on lovable).