Enforce overlay provenance for main rebuilds

[jeonghun-jj-lee]

Important

Problem - Rebuild Locally and Rebuild from Main have different source contracts, but only the local contract is currently reliable. Rebuild from Main can combine Amicode main with an OpenCode revision whose tracked overlay is stale or has incomplete provenance, silently producing a mixed UI.
Approach - Keep Rebuild Locally as a raw, current-worktree build that ignores the overlay. Make Rebuild from Main a verifier of a committed cross-repository promotion: Amicode main must carry a complete overlay and manifest for the exact OpenCode local/amicode revision it builds. Introduce an explicit, reviewable overlay-promotion workflow; rebuilds never write source files.
Approaches considered - Automatically synchronize during Rebuild from Main was rejected because it would modify the checked-out Amicode worktree, could capture dirty OpenCode state, and previously overwrote Amicode-side fixes. Treating the overlay as optional for main rebuilds was rejected because it permits unreproducible mixed UI states.
Scope - in: explicit full overlay promotion, manifest provenance, main-rebuild verification, CI enforcement, and regression coverage; out: changing the Rebuild Locally source contract or redesigning unrelated developer tooling.
Assumptions - local/amicode is the authoritative fork branch for the promoted app source, and a synchronization commit is merged into Amicode main after each promoted fork revision.

Acceptance Criteria

• Rebuild Locally performs no checkout, fetch, rebase, overlay materialization, or overlay validation; it builds directly from the selected local Amicode and OpenCode worktrees, including local changes.
• Rebuild from Main continues to check out and update Amicode main and OpenCode local/amicode, then resolves both exact revisions before installing or building.
• Rebuild from Main refuses to continue when Amicode main's recorded OpenCode revision differs from the checked-out local/amicode revision, with an actionable status explaining that an overlay-promotion commit must be merged first.
• Rebuild from Main refuses to continue when the overlay's content, file set, deletions, or manifest provenance does not reproduce the declared OpenCode revision.
• A promotion command generates the full overlay from one explicit clean OpenCode revision, including additions and deletions, and atomically updates all manifest provenance and file hashes.
• The promotion command never consumes a dirty OpenCode worktree or silently writes an Amicode branch during a rebuild.
• Overlay-only files are either present in the declared OpenCode revision or recorded as deliberate, reviewed exceptions; unexplained drift fails verification.
• The currently documented overlay sync commands are executable package commands and their behavior matches the documentation.
• The prompt-bubble visual treatment follows local/amicode after a completed promotion and main rebuild; overlay-only stale styling cannot affect the built app.

Testing Decisions

Extend the existing developer-tools bridge tests for local and main rebuild behavior. Extend overlay synchronization tests with isolated fixture repositories; tests must never mutate the developer's real fork or overlay. Reuse the app-bundle drift and packaging gates for provenance, file-set, and generated-bundle verification. Add a cross-repository CI lane that reads the declared OpenCode revision and verifies the committed Amicode overlay against it.

Key Decisions

Rebuild Locally is intentionally permissive and overlay-independent. Rebuild from Main is intentionally strict and read-only with respect to source trees. Synchronization is an explicit cross-repository promotion that produces a reviewable Amicode commit; it is not a side effect of rebuilding. The fork remains the source of truth for app source, while Amicode main records the reproducible tracking artifact for each promoted fork revision.

Data Contracts

The overlay manifest owns the declared OpenCode tag and immutable commit SHA, upstream-base provenance, complete overlay file hashes, and complete deletion set. Main rebuild verification requires the checked-out OpenCode SHA to equal the manifest SHA and the regenerated overlay to equal the committed overlay. A promotion receipt must identify the source revision and the generated manifest revision.

Constraints & Invariants

No direct commit to main. No source-tree writes from either rebuild button. Local rebuild must retain support for divergent branches and uncommitted work. Main rebuild must fail closed rather than serve a mixed app. A synchronization PR must contain only deliberate generated overlay/provenance changes plus the validation required to establish the invariant.

Prior Art

Developer Tools rebuild bridge, app-bundle materializer and extraction flow, overlay synchronization checker, app-bundle drift gate, the known-fix pre-sync guard, and the current local OpenCode promotion branch.

Notes

The initial migration must reconcile the overlay's outdated recorded fork provenance with the currently promoted OpenCode revision before strict main-rebuild verification is enabled.