Adopting an existing wordpress-develop checkout

Updated 15 September 2026. Written before #364 was decided. Both blockers at the end were properties of the retired JavaScript engine and no longer apply, so what remains is the adopt flow with nothing gating it.

The gap

The app can only work with a checkout it cloned itself. A developer who already has a wordpress-develop checkout — years of history, their fork as a remote, their own branches — cannot bring it in; their choice is a second multi-gigabyte clone or staying out. These are exactly the people the collaboration scope (#107) counts on: the mentors, the committers at the next table, the contributor who outgrew the training wheels and wants the app's environment without abandoning their repository.

This is the entry door of #350's second invariant: the app meeting, on day one, a repository it did not create and cannot have assumptions about.

The idea

An adopt flow, deliberately cautious in three steps:

• Validate. Is this wordpress-develop; which remote is the canonical upstream (the user's origin is very often their fork, with upstream under another name); is the tree dirty; is anything mid-flight. The app asks what it cannot infer rather than guessing — the existing precedent of refusing to invent a branch's base rather than deriving it from today's trunk is the right instinct, generalised.
• Refuse the exotic, by name. Linked worktrees, sparse checkouts, submodule arrangements, anything the bundled implementation cannot faithfully represent: a clear "this repository uses a feature the app does not support, and here is which" at import time. A loud early no is a feature; a quiet later corruption is the one unforgivable outcome.
• Adopt under the contract. The imported site runs in the adopted tier: the app respects foreign branches and commits, never rewrites history it did not create, and drops the managed tier's "you cannot break anything" promise openly — the person importing a real checkout has already accepted that trade everywhere else they work.

One thing gets easier here, worth saying out loud: a full clone carries its history, so merge bases for #351 come straight from the repository with no fallback path needed. Imported checkouts are the easy case for the engine and the hard case for everything around it.

Spike first — no longer needed

Both blockers named here belonged to the JavaScript engine, and #364 resolved it: the app ships a real Git binary and isomorphic-git is gone from the dependency tree (#411).

• The survey of aged repositories. Moot. The question was whether the bundled implementation could read packed refs, pack formats and index versions that Git itself had maintained for years. Git reads them.
• The .lock blocker. Moot, and this was the harder of the two. The old implementation wrote no lock files at all, so it did not participate in Git's ref-update protocol and its locking was an in-process mutex that protected nothing against a second process — fatal for a checkout shared with someone else's Git. Real Git takes .lock files like any other Git.

This issue is therefore cheaper than it reads. What is left is the flow itself — validate, refuse the exotic by name, adopt under the contract — with no spike in front of it.

The issue names no files, tests, or entry points. Start by tracing how the app currently creates and validates cloned checkouts and how it invokes Git; define the adoption flow's validation and unsupported-feature errors, then verify that an existing wordpress-develop checkout can be adopted without rewriting foreign branches or commits.