Proposal: scope-based skill resolution and organizational inheritance for primitives

[RudsonCarvalho]

Problem

Picture a multinational group. The HQ platform team publishes a global code-review skill (or a compliance / data-handling instruction set) as an APM package. Each subsidiary then needs to narrow it for local rules — GDPR in the EU entity, central-bank reporting requirements in another, sector regulators elsewhere. The base is 90% shared; only the regulatory delta differs per country.

Today the only way to express that delta is copy-and-modify: fork the package, edit a few lines, re-publish under a new name. The cost shows up later:

• Silent drift — when HQ revises the base, every fork is now stale and nobody is notified.
• Lost lineage — there's no machine-readable record that acme-br/code-review is acme/code-review plus a regional override.
• N update points — a one-line base change means N manual edits across N subsidiaries.

Why APM is the right layer

APM already owns the primitives that make this tractable: version pinning, apm.lock.yaml for provenance, registries/marketplaces for distribution, and policy composition. Crucially, APM already does hierarchical inheritance — on the policy plane: apm-policy.yml supports extends: with a tighten-only merge across the enterprise-hub → org → repo chain (up to 5 levels deep), with a deterministic merge-rule table and detectable lineage.

So scope-based resolution isn't an alien concept here — the machinery exists for policy. The proposal is to offer an analogous, opt-in model for primitives (skills, instructions, prompts), where the merge semantics differ: instead of tighten-only allow/deny, it's most-specific-wins override plus non-overridable invariants declared by the parent scope.

Proposed concept

• Scope chain with precedence — a primitive resolves along a declared chain (e.g. global → country → business-unit); the most specific scope wins on conflict.
• Non-overridable invariants — a parent scope can mark parts of a primitive as locked, so a child can extend but not weaken them (the primitive-plane analogue of tighten-only).
• Lineage in the lockfile — apm.lock.yaml records which scope each resolved primitive came from, so the base→override relationship is auditable rather than implied by a fork.
• Federated publication — HQ publishes the base package; subsidiaries publish overrides as dependent packages to private registries/marketplaces, instead of forking.

A strawman apm.yml. Note which lines are existing syntax vs. proposed:

name: acme-brazil-agents
version: 1.0.0

# `extends:` at the manifest level is PROPOSED. Today `extends:` exists only
# in apm-policy.yml, not in apm.yml.
extends:                                          # proposed syntax
  - acme-corp/global-agents#v3.2                  # base scope

dependencies:
  apm:
    # Sub-path primitive refs are EXISTING apm.yml syntax.
    # The `override:` mapping is PROPOSED — no such key exists in APM today.
    - acme-corp/global-agents/skills/code-review:           # existing ref form
        override: acme-br/regional/skills/code-review-lgpd  # proposed syntax
    - acme-br/regional/instructions/bacen-reporting         # existing ref form

Open questions

1. Does this belong in APM core, or as an extension on top of the existing dependency resolver?
2. How should it interact with apm-policy.yml's tighten-only merge — one composition engine for both planes, or two with shared lineage?
3. What's the right conflict/precedence rule when an overridden primitive is deployed across multiple targets (Copilot, Claude, Cursor…) that each have their own loading order?

This overlaps with the governance/composition direction in #148 and the monorepo-scoping question in #1546 — happy to fold it into either if maintainers feel it fits better there.

I explored this pattern (Hierarchical Skill Resolution) in more depth here: https://doi.org/10.5281/zenodo.20619456