# ADR-008: First-Parent Ordering in Reconciliation Merges

**Status:** Accepted
**Date:** 2026-02

## Context

Josh-proxy uses **first-parent traversal** when mapping subrepo history back to the monorepo. When you push a commit through josh-proxy, josh walks the first-parent chain to find a commit it can map to a monorepo commit. If the first parent leads to unmappable history, josh cannot reconstruct the monorepo-side branch correctly.

This became critical when the reconciliation merge (ADR-007) initially had the wrong parent order: old subrepo history as parent 1, josh-filtered as parent 2. Josh followed parent 1, couldn't find any mappable commit, and created a monorepo branch containing only the subrepo subfolder content — effectively deleting 1280 files from the rest of the monorepo.

## Decision

In reconciliation merge commits, the josh-filtered HEAD **must be parent 1** (first parent). The old subrepo HEAD is parent 2.

```bash
git commit-tree "$josh_tree" \
  -p "$josh_head" \      # parent 1: josh-filtered — josh follows this
  -p "$subrepo_head" \   # parent 2: old history — side branch, ignored by josh
  -m "..."
```

### Why this is safe

- The old subrepo HEAD (`subrepo_head`) is still an ancestor of the merge commit regardless of parent order — push succeeds either way
- `--ancestry-path` in reverse sync still follows `B → M → C` regardless of parent order (it traces all paths, not just first-parent)
- Josh follows first-parent and finds the josh-filtered commit, which maps cleanly back to the monorepo

## Consequences

**Positive:**
- Josh can map the reconciliation merge back to the monorepo correctly
- Reverse sync through josh produces correct diffs (only subrepo-scoped changes)
- `git log --first-parent` on the subrepo shows the clean josh-filtered lineage

**Negative:**
- This is a subtle invariant — future changes to merge commit creation must preserve parent order
- The constraint is undocumented in josh-proxy's own documentation (discovered empirically)
- No automated test can verify this without a running josh-proxy instance

**Lesson learned:**
Parent order in `git commit-tree -p` is not cosmetic. For tools that rely on first-parent traversal (josh-proxy, `git log --first-parent`), parent 1 must be the "mainline" that the tool should follow.