monorepo: return path-policy errors that name allowed roots and the next action

[genedna]

Summary

Several first-use failures expose internal protocol wording instead of the configured Monorepo path policy:

• Pushing a root commit under an unsupported top-level path reports Can not init directory under monorepo directory!.
• Pushing a root commit to a valid but uninitialized child path can report push chain is broken.
• The user must independently discover the configured root directories, the difference between ImportRepo and Monorepo paths, and the create-entry prerequisite.

These conditions require different remediation, but the current messages do not identify which condition occurred or what a user should do next. The resulting trial-and-error is especially costly because root-directory policy is deployment-specific.

Versions and environment

• Mega2 image: genedna/mega2:latest
• Deployment: local macOS OrbStack evaluation stack
• Client: standard Git and Libra 0.23.46
• Storage-only trunk deployment

Reproduction

1. Push a new root commit to a path whose first component is not an allowed Monorepo root.
2. Push a new root commit to a valid root with an uninitialized child path.
3. Compare both responses with a real non-fast-forward push against an existing path.

The first two user errors need different next actions, while a non-fast-forward needs repository alignment.

Actual behavior

• Internal phrases and generic first-parent-chain diagnostics are surfaced as the principal message.
• The response does not name allowed roots, classify the target path, or identify the provisioning action.
• A generic alignment hint can be misleading when no compatible remote history exists.

Expected behavior

The service returns stable, security-conscious path-policy diagnostics:

• An invalid top-level path identifies the path-policy violation and supplies safe allowed roots or a documentation link.
• A valid but uninitialized child path identifies that initialization is required and points to the supported scaffold or create operation.
• A genuine non-fast-forward retains its existing alignment guidance.
• The contract is consistent across Git Smart HTTP errors and applicable product APIs.

Scope boundaries

In scope:

• Error classification and remediation for Monorepo path policy.
• Structured error codes and human-readable messages.
• Documentation that makes the browser and supported creation workflow discoverable.

Out of scope:

• Revealing credentials, filesystem locations, or other secret deployment configuration.
• Creating new top-level roots from a Git push.
• Changing the configured root-directory authorization policy.

Acceptance criteria

1. An unsupported top-level target returns a stable path-policy error and a safe remediation that does not require source-code reading.
2. An uninitialized valid child path returns a distinct error code and explains the provisioning prerequisite.
3. A real non-fast-forward remains distinguishable and continues to recommend alignment rather than provisioning.
4. Error messages do not rely on Can not init directory under monorepo directory! or push chain is broken as the only user-facing explanation for these cases.
5. Git and API tests cover all three cases, including custom monorepo.root_dirs configuration.
6. The README, quick-start, and user guide link to one authoritative first-use path-policy section.

Related evidence

• User trial report dated 2026-09-23, P2 usability findings and appendix D.
• Existing product policy: configured monorepo.root_dirs, ImportRepo under /third-party, and storage-only path writes.