Make core-plus-project layering a declared, verified contract carried by structured composition and project-local provider projections, because the required cross-provider discovery surfaces are not uniformly inherited across a repository boundary.
Composition is structural: ordered InstructionUnits resolved into an InstructionComposition receipt, projected into provider-native targets inside each project root.
The project layer stays project-owned and byte-preserved; the core layer is identified by an exact pinned release digest.
Ancestor placement is a provider-specific projection strategy for the single client that honors it, never the general delivery surface.
Measured discovery boundary
The required cross-provider discovery surfaces are NOT uniformly inherited across a repository boundary. Measured across a real git-root boundary with child-local positive controls distinguishing a boundary miss from a broken probe: exactly one client inherits a parent instruction file — the measured exception — while parent skills are inherited by NO client and the remaining clients inherit neither surface.
A fixture WITHOUT a git root in the child silently converts a boundary miss into a false positive: the identical client, prompt, and fixture flipped from inheriting both surfaces to inheriting neither when a git root was added to the child. Any future probe that omits the boundary is invalid.
One client’s cells were additionally constrained by a vendor unsupported-client response for the installed tier, which the provider supported-status contract owns.
Native discovery would supply placement and precedence only. Layer attribution, conflict detection, immutability, and pinning are NOT supplied by it and are owned by this section regardless.
Verification
Every fixture artifact exists at exactly one level AND the child is a real repository root, so a positive cannot be explained by a project-local copy nor by an absent boundary.
Carry child-local positive controls so an ABSENT result proves a discovery boundary rather than a malformed probe.
Assert BOTH a core-only and a project-only unit resolve, on both the instruction and skill surfaces, per client.
Fail closed when a client changes its discovery behavior, when two layers claim one logical key, and when the composition digest does not match the project pin.
Run focused pytest and the owning runtime self-test with a 150-second test timeout.
Work Items
Define InstructionUnit and InstructionComposition as first-class contracts: stable unit id, owning layer (core or project), content digest and source, provider applicability, ordering constraints, and provenance; plus an InstructionComposition receipt over the ordered units. Rendered provider entrypoints are OUTPUTS of this composition and never merge inputs.
Add an instruction-artifact logical asset category. CLAUDE.md, AGENTS.md, and GEMINI.md are provider-specific projection targets within it, never canonical asset names.
Project provider-native artifacts INSIDE each project root, because the required cross-provider discovery surfaces are not uniformly inherited across a repository boundary. Measured across a real git boundary: parent-level skills are inherited by NO client, and Codex, OpenCode, and Gemini inherit no parent instruction either; one client’s parent instruction file is the single measured exception and is handled as a provider-specific strategy. An ancestor AI OS directory cannot be the sole delivery surface.
Treat Claude’s parent-instruction inheritance as a PROVIDER-SPECIFIC projection strategy, not the general mechanism: it is the single measured cell that crosses a repository boundary, and its placement plus the ordered units it contributes still require a receipt and an acceptance probe.
Emit skill projections into each project root for EVERY provider in the recorded required-provider set, so a declared successor is projected and a removed provider is not. The shared .agents/skills alias is a conditional optimization for the initial families that consume it (Codex, OpenCode, Gemini), applied only when those providers are in the required set; it is an adapter optimization and never parent inheritance.
Define per-category composition semantics: instructions compose as ordered units with the project layer inheriting core; skills, rules, and commands union by logical key with distinct keys coexisting and same-key claims failing closed absent an explicit digest-aware override.
Carry layer attribution and provenance through every projection: each generated target resolves to its ordered source units and their owning layer, so a core rule cannot silently drift into looking project-specific and a rendered artifact can answer which layer owns it.
Detect and fail closed on cross-layer conflicts: two layers claiming one logical key, a project unit shadowing a core unit without a recorded override, and a composition digest that does not match the project’s pin.
Prove discovery with fixtures that CROSS A REAL REPOSITORY-ROOT BOUNDARY, since a fixture without a git root in the child silently converts a boundary miss into a false positive. Assert a core-only unit and a project-only unit both resolve, on the instruction and skill surfaces, per client, with child-local positive controls distinguishing a discovery-boundary miss from a broken probe.