# ADR-013: Non-destructive adoption merge for existing subrepos

**Status:** Accepted
**Date:** 2026-04

## Context

Existing subrepos often already have real history, open PRs, and developer clones.
The original `import` then `reset` onboarding path establishes Josh-compatible
history by force-pushing the Josh-filtered monorepo history onto the subrepo.
That is correct for empty replacement repos, but it rewrites the active subrepo
branch and invalidates local clones.

We need a path for active subrepos where history must remain available on the
same branch and where open PR branches should stay based on the existing history.

## Decision

Add `josh-sync adopt <target>` as a separate workflow from `onboard` and `reset`.
Adoption imports the subrepo content into the monorepo, waits for the import PR
to merge, then creates one merge commit on each configured subrepo branch:

1. First parent: Josh-filtered monorepo HEAD
2. Second parent: existing subrepo HEAD
3. Tree: Josh-filtered monorepo tree

Josh follows first-parent history back to the monorepo, while Git still keeps
the old subrepo history reachable through parent 2. The push is a normal
fast-forward push from the existing subrepo HEAD to the adoption merge commit.
No force-push is used.

Before creating the adoption merge, josh-sync requires the existing subrepo tree
to match the Josh-filtered monorepo tree. If the trees differ, adoption aborts
and the user must merge the import PR or reconcile the branch contents first.

Adoption state is stored separately at `<target>/adopt.json` on the
`josh-sync-state` branch.

## Consequences

**Positive:**

- Existing subrepo history remains on the active branch.
- Existing clones can fast-forward instead of hard-resetting or re-cloning.
- Open PR branches remain based on reachable history.
- Josh-compatible ancestry is established without a destructive rewrite.

**Negative:**

- Adoption adds one synthetic merge commit to each adopted subrepo branch.
- Strict "no subrepo commit at all" adoption is impossible if the existing
  subrepo branch must become connected to the Josh-filtered history without a
  rewrite. A commit is needed to join the two histories.
- Tree equality is strict. If the monorepo import differs from the subrepo
  content, adoption stops until the user resolves the mismatch.