import: reconcile ImportRepo documentation with its one-shot receive-pack behavior

[genedna]

Summary

The public quick-start and README describe ImportRepo under /third-party/** as following ordinary Git semantics, with multiple branches, client tags, direct modification, and continued upstream tracking. In a storage-only evaluation stack, the first push succeeds but a second push to the same ImportRepo leaf is rejected:

attach B3 did not complete successfully: path <path> already exists in monorepo tree (cannot attach leaf)

The same behavior was reproduced with a standard Git client, so this is not limited to Libra. The current product contract is therefore ambiguous: the recommended destination behaves as a one-shot import, while user-facing documentation implies an updatable hosted repository.

Versions and environment

• Mega2 image: genedna/mega2:latest
• Deployment: local macOS OrbStack evaluation stack
• Transport: standard Git Smart HTTP and Libra 0.23.46
• Import path: /third-party/workbuddy/demo

Reproduction

1. Create a local Git or Libra repository with an initial commit.
2. Push it to a new ImportRepo path under /third-party; the push succeeds.
3. Add another commit on the same branch.
4. Push again to the same remote path.

The second push is rejected because the target leaf already exists.

Actual behavior

• ImportRepo accepts the initial import but does not accept a normal follow-up push.
• The rejection uses an internal attach failure rather than a product-level explanation.
• The quick-start does not state that ImportRepo is import-once, even though it recommends the location for repositories expected to track upstream.

Expected behavior

Mega2 must choose and document one coherent contract:

1. ImportRepo supports ordinary incremental Git updates, including the documented multiple branches and tags; or
2. ImportRepo is explicitly an immutable or one-shot import facility, and the service, CLI guidance, and documentation say so before a user chooses the path.

Scope boundaries

In scope:

• Defining the update semantics of ImportRepo.
• Making the receive-pack error reflect the chosen semantic.
• Aligning README, quick-start, user guide, and Monorepo documentation.
• Regression coverage with both a standard Git client and Libra.

Out of scope:

• Enabling multiple branches or client tags in ordinary Monorepo paths.
• Silently converting an existing ImportRepo into a Monorepo subtree.
• Changing the meaning of a completed import without a migration plan.

Acceptance criteria

1. The public documentation has one unambiguous statement about whether an ImportRepo can receive a second push.
2. If updates are supported, a second fast-forward push changes the served repository and remains cloneable with Git and Libra.
3. If ImportRepo is intentionally one-shot, the second push fails with a stable semantic error code such as IMPORT_REPO_IMMUTABLE, explains that the initial import is retained, and directs users to the appropriate updatable path.
4. The error must not present a generic cannot attach leaf implementation detail as the only explanation.
5. The selected policy has integration coverage for initial import, follow-up push, clone, and tags where the policy permits them.
6. Existing ImportRepo data has a documented compatibility and migration story.

Related evidence

• User trial report dated 2026-09-23, section P1-1.
• Current documentation calls ImportRepo an ordinary-Git exception and recommends continued upstream maintenance.