PROP-023 — Bridge packages

**Status: IMPLEMENTED** (specified 2026-06-24 in an owner-requested design session; verified against the tree 2026-07-25 by the spec-actualization campaign). The umbrella's own addition — `[package].bridge`, defaulting to false — parses in `vibe-core` with a doctest, and the mechanisms it composes all ship: [PROP-020](../vibe-workspace/PROP-020-install-hooks.xml) install hooks, [PROP-021](PROP-021-submodule-sources.xml) submodule sources, [PROP-022](../vibe-workspace/PROP-022-materialization-modes.xml) materialization modes, plus [PROP-021 §2.2](PROP-021-submodule-sources.xml#source-abstraction) dependency-declared embedded sources — so every bridge class recorded here has live machinery. The umbrella adds a flag and packaging/provenance conventions; each underlying mechanism remains independently usable.

**Related:** [PROP-002](PROP-002-decentralized-registry.xml) (a bridge is an ordinary package + identity), [PROP-008](PROP-008-qualified-naming.xml) (the consumer-facing qualified product coordinate), [PROP-015 §2.6](../vibe-mcp/PROP-015-mcp-integration.xml#skill) + [PROP-015 #skill-include](../vibe-mcp/PROP-015-mcp-integration.xml#skill-include) (projecting a skill out of the bridged subtree, selectively), [PROP-000 §16](../../common/PROP-000.xml) (the installable kinds a bridge still belongs to).

People publish skills and projects to GitHub / GitVerse without ever making a vibevm package — out of disinterest, or because their repo's layout has nothing to do with vibevm conventions. That work is then unreachable through `vibe install`, and the original author has no incentive to change. A **bridge package** closes the gap without the author's involvement: a *maintainer* volunteers to steward someone else's repository and publishes an ordinary vibevm package that **wraps** it. The bridge makes the foreign repo consumable by vendoring it, carrying a git-native submodule, or declaring an immutable external embedded source. The reference-backed form keeps upstream bytes out of the bridge repository and fetches them directly from the author.

A bridge is not a new kind of package or a new subsystem. It is:

an ordinary package (still one of `flow` / `feat` / `stack` / `tool`), carrying the foreign repo as **vendored** content, a git-native **submodule**, or a manifest-declared immutable **external embedded source** ([PROP-021](PROP-021-submodule-sources.xml)), optionally **prepared** by install hooks ([PROP-020](../vibe-workspace/PROP-020-install-hooks.xml)), optionally **materialised** as `in-place` when the upstream is a giant ([PROP-022](../vibe-workspace/PROP-022-materialization-modes.xml)), with any skill projected selectively from the bridged subtree ([PROP-015 #skill-include](../vibe-mcp/PROP-015-mcp-integration.xml#skill-include)).

…plus one flag that says "this is a bridge."

`req r1`

`[package].bridge = true` marks a package as a bridge. It does **not** change the package's `kind` (a bridged skill is still a `feat`/`tool` as appropriate) or its identity. The flag is metadata with two jobs: it documents that the package's substantive content is *foreign* (stewarded, not authored, by the maintainer), and it is the hook the registry/UI uses to surface provenance (§2.4). Default `false`; the overwhelming majority of packages are not bridges.

`req r1`

A bridge obtains the upstream repo in one of three ways:

**Vendored ("git in git")** — the maintainer copied the upstream tree into the package and committed it. This needs **none** of PROP-021/022 machinery: it is plain files in a `snapshot` package. A vendored bridge is therefore the cheapest case — the flag (§2.1) plus, if the layout needs shaping, hooks. **Submodule-backed authoring** — the maintainer workspace references upstream through a Git submodule ([PROP-021](PROP-021-submodule-sources.xml)). A direct Git-source install preserves that live Git composition. Registry publication deliberately flattens a clean populated gitlink into ordinary package files, removes `.gitmodules`, and reports `submodule <path> vendored at <sha>`; the published package is therefore a truthful vendored snapshot, not a dangling promise that consumers will recurse into the maintainer's repo. **Reference-backed** — the package repository contains only maintainer-authored metadata and adapters. `[[embedded_source]]` declares the original public Git URL, an immutable full commit, an independently verified source-tree hash and upstream licence provenance. Installation fetches that exact source directly into the consumer's machine cache; selected `[[skill]]` content or `[[skill.resource]]` files are projected from the authenticated cached tree. The upstream is not copied into the bridge repository, is not resolved as a vibevm dependency node, and its own `vibe.toml`, hooks and submodules are never executed implicitly. The installed bridge itself remains a normal physical `vibedeps` slot; source-aware loaders combine that owner root with named, separately authenticated external roots without pretending the latter are UPL package payload.

The maintainer chooses per trade-off: vendored is self-contained; submodule-backed uses Git's native composition; reference-backed preserves repository and licence boundaries but needs the pinned upstream once per machine-cache miss.

`req r1`

A bridge is the point where the three orthogonal mechanisms compose, but it mandates none of them:

a bridge **without hooks** is valid (the upstream layout already fits); a bridge **without a submodule** is valid (vendored); a bridge **without `in-place`** is the norm (`in-place` is only for giant upstreams). The canonical full case — submodule-backed + `pre-install` hook to shape the tree + selective skill projection — is the union of the four specs, but each piece is independently usable outside any bridge. This is why they are four specs and four test sets, not one (the owner's orthogonality requirement).

`req r1`

The bridge's **maintainer** is distinct from the upstream **author**. `[package].authors` names only the people or organisations that authored the package's own metadata, adapters and other maintainer-owned payload. It never absorbs the authors of referenced bytes. Every `[[embedded_source]]` records those separately as a non-empty `upstream_authors` list. Listings, locks and indexes preserve both lists under their own labels; they never concatenate them into one ambiguous authorship claim. The package's qualified coordinate ([PROP-008](PROP-008-qualified-naming.xml)) names the **product a consumer installs**, not the codebase in which its packaging machinery happened to be written. Packaging Spec Kit does not make it `org.vibevm/*`; its product coordinate may be `org.speckit/speckit`. Packaging Matt Pocock's collection may be `com.mattpocock/skills`. The distinct steward remains visible through `[package].authors`, the package distribution `source_url`, `bridge = true`, and the upstream repository/PURL recorded by `[[embedded_source]]` and `describes`. A consumer can therefore see three separate answers: *what product is this* (coordinate), *who maintains this packaging* (authors + distribution source), and *what original bytes does it wrap* (upstream provenance). **Not everything we package belongs to VibeVM.** A third-party product's package source defaults to its own Git repository outside the VibeVM monorepository and outside `org.vibevm/*`. Before scaffolding a bridge, the maintainer must explicitly ask the owner whether the package belongs in an existing product workspace or should be an independent repository. Silence never authorises absorbing a foreign product into the VibeVM namespace. Locally, independent package repositories may live under a neutral collection such as `~/git/v/packages/`; publication still maps one package repository to one registry repository. A bridge records two distinct legal surfaces: `[package].license` describes only the maintainer-authored bridge package, while every external embedded source records its upstream licence and an immutable licence URL. A bridge never presents upstream bytes as relicensed by the bridge maintainer. A skill that lives inside the bridged subtree is projected through the normal skill machinery, using the `include` selector ([PROP-015 #skill-include](../vibe-mcp/PROP-015-mcp-integration.xml#skill-include)) to pick the relevant files out of an upstream tree full of unrelated content.
**A `bridge` package kind** (a kind of its own beside the §4.1 register) — rejected: the kinds describe *what the package is for*; "bridge" describes *where its content came from*. They are orthogonal axes, so bridge is a flag, not a kind. (The reasoning survives the register later growing `mcp` — that kind, too, says what a package is FOR.) **Auto-importing a foreign repo with no maintainer** — rejected: someone must take responsibility for shaping, updating, and vouching for the wrapped code; an unowned auto-bridge has no one to fix it when upstream moves or breaks.
**Automatic conversion of foreign layouts** into vibevm conventions — bridges shape upstream with explicit, maintainer-written hooks, not inferred magic. **Security scanning of wrapped third-party code** — the LLM "antivirus" is the same far-backlog item as for hooks ([PROP-020 §4](../vibe-workspace/PROP-020-install-hooks.xml#out-of-scope)); a bridge's trust posture is dependency selection plus the installed extension observability defined by PROP-054, an explicitly accepted risk for now. **Automated legal interpretation or compatibility adjudication** remains out of scope. Mechanical provenance is in scope: the bridge licence and each external source's upstream licence/immutable licence URL are recorded and displayed as separate facts.
`[package].bridge` parses as a boolean, defaults `false`, and does not alter `kind` or identity. A vendored bridge installs as a plain `snapshot` package (flag + optional hooks), with no submodule/materialization machinery engaged. A Git-source submodule-backed bridge fetches upstream recursively ([PROP-021](PROP-021-submodule-sources.xml)). Registry publication instead verifies and flattens each clean populated gitlink, omits Git metadata, reports the exact vendored commit, then ordinary install/hooks/skill projection consume that plain snapshot. A reference-backed bridge repository contains no upstream files or gitlinks; install authenticates the declared immutable source into a machine-local cache, records the pin in `vibe.lock`, and projects only the declared skill paths/resources without executing upstream package machinery. Its normal bridge payload is still materialised in `vibedeps`, and an operator can ask for either the package root or an authenticated named source root. Product identity, packaging stewardship and upstream URL/PURL are separately recoverable for a bridge package; none is inferred from another. Package authors and upstream authors are required, stored and displayed as separate provenance fields. A third-party package is not placed below `org.vibevm` or in VibeVM's monorepository without an explicit owner decision; the scaffolding workflow asks this boundary question before choosing its coordinate or repository. Full `self-check.sh` green; conform 0/0/0; specmap clean.