Skip to main content

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.

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

CommandEffect
npm run sync:mirror:statusDry-run: fetch and report status, no push
npm run sync:mirrorNormal mirror: push origin → encore_lovable (fails fast on divergence)
npm run sync:mirror:force-resetDESTRUCTIVE: 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

git fetch origin encore_lovable
git log --oneline --left-right --graph \
    origin/development...encore_lovable/development
  1. Identify commits that should be preserved.
  2. Create a branch off origin/development: 
    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): 
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

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).