feat(policy): add dependencies.require_pinned_constraint to ban unbounded ranges

[danielmeppiel]

Summary

Add a new boolean field policy.dependencies.require_pinned_constraint
to apm.policy.yml. When set to true, apm install (and apm audit)
flags any dependency whose constraint is unbounded — *, a bare
>=X.Y.Z without an upper bound, or a bare branch ref — and routes
through the existing enforcement: warn | block | off setting.

Motivation

Governed installs rely on lockfiles to deliver reproducibility, but
the apm.yml manifest itself can express intent that defeats lockfile
discipline on the next apm update. A dep written as:

dependencies:
  apm:
    - acme-org/some-skills        # no ref - tracks default branch
    - other-org/lib@>=1.0         # no upper bound - any 99.x is valid
    - third-org/pkg#*             # any version

Will resolve to whatever exists today, but the next apm update may
pull a major-version jump or a moving branch tip. Enterprise audit
flows want to declare "we only ship deps that pin to a bounded
constraint." That is what this policy field expresses.

Proposal

Add a single additive field on DependencyPolicy:

@dataclass(frozen=True)
class DependencyPolicy:
    allow: tuple[str, ...] | None = None
    deny: tuple[str, ...] | None = None
    require: tuple[str, ...] | None = None
    require_resolution: str = "project-wins"
    max_depth: int = 50
    require_pinned_constraint: bool = False    # NEW

YAML:

# apm.policy.yml
policy:
  enforcement: block          # existing field, governs how violations surface
  dependencies:
    require_pinned_constraint: true

A dep's constraint is considered "unbounded" if any of the following
hold:

1. The ref is missing / empty (resolves to default branch).
2. The ref is a bare branch name (anything that does not parse as a
   semver range and is not a SHA or literal tag).
3. The semver range is *, x, X, or a single-sided lower bound
   without a paired upper bound (e.g. >=1.0.0 alone).
4. The constraint is a SHA-resolved branch alias under a name that
   moves (we keep this case as a follow-up — a SHA is technically
   pinned even if it came from a branch).

Conversely, the following count as pinned:

• Exact semver (1.2.3).
• Caret/tilde ranges (^1.2.3, ~1.2.3).
• Bounded ranges (>=1.0.0 <2.0.0, 1.x).
• Literal tag refs (v1.2.3).
• Full SHA refs.
• Local-path deps (source: local) — no version to pin.
• Registry deps with a version field already present (covered by
  PR feat(registry): [FEATURE] Add package registry support for dependency… #1471 + feat(deps): resolve semver constraints on git-source dependencies against repo tags #1488).

The check runs in the policy preflight phase (alongside
run_dependency_policy_checks) on the declared constraints, not
the resolved ones, so the policy is meaningful before the install
completes.

Examples

With require_pinned_constraint: true and enforcement: block:

# apm.yml
dependencies:
  apm:
    - acme-org/skills              # FAIL: no ref
    - other/lib@>=1.0              # FAIL: unbounded upper
    - third/lib#^1.2.0             # OK: caret range
    - fourth/lib@v1.5.3            # OK: literal tag

Output:

[x] Policy violation: 2 dependencies use unbounded constraints.
    - acme-org/skills          (no ref; resolves to default branch)
    - other/lib@>=1.0          (unbounded upper; pair with '<2.0' or use '^1.0')
    Hint: pin to a semver range, literal tag, or SHA.
    Enforcement: block. Install aborted.

With enforcement: warn, the same lines render with [!] and install
proceeds.

Considerations

• Default false — no behavior change for existing users.
• Does not collide with policy.dependencies.require (which is an
  allowlist of required dependency names). The new field is a
  property check, not an allowlist.
• Composes with enforcement the same way every other dependency
  policy check does — no new enforcement axis.
• Interaction with feat(deps): resolve semver constraints on git-source dependencies against repo tags #1488. If feat(deps): resolve semver constraints on git-source dependencies against repo tags #1488 lands first, git-source deps
  may carry semver ranges. The unbounded-range check applies
  uniformly across all three sources (git, marketplace, registry).
• Transitive deps. The check runs on direct deps only by design —
  the consumer cannot rewrite a transitive dep's constraint. (We could
  extend transitively in a follow-up, but the value is at the
  authoring surface.)

Out of scope

• A separate allowlist of "approved unbounded patterns" (e.g. allow
  main on internal repos). If demand surfaces, follow up with
  require_pinned_constraint: {except: [...]}.
• Enforcement of registry-pinned hashes (registry deps already pin
  via resolved_hash in the lockfile, per feat(registry): [FEATURE] Add package registry support for dependency… #1471).
• Migrating the existing require_resolution semantics.

References

• PR feat(registry): [FEATURE] Add package registry support for dependency… #1471 added RegistrySourcePolicy alongside DependencyPolicy
  in src/apm_cli/policy/schema.py.
• Existing call sites for dependency policy checks:
  policy_gate, policy_target_check, run_policy_checks,
  run_policy_preflight.
• Inspiration: npm config set save-exact true, pip's
  --require-hashes, cargo workspaces' resolver lockstep.

Related

• feat(deps): resolve semver constraints on git-source dependencies against repo tags #1488 — Git-source semver. The classification logic in this issue
  applies uniformly across all three resolution sources; feat(deps): resolve semver constraints on git-source dependencies against repo tags #1488 brings
  git into that set.
• feat(policy): add custom_checks for arbitrary subprocess validation in apm-policy.yml #519 — custom_checks framework for apm.policy.yml (pluggable
  subprocess validators). This issue is intentionally a built-in
  field, not a custom_checks entry — same precedent as the existing
  allow / deny / require fields. Rationale: enterprise-default
  governance concern, deterministic constraint-string analysis, no
  subprocess required. Enterprises can stack both (built-in pinning
  check + custom subprocess validators) once feat(policy): add custom_checks for arbitrary subprocess validation in apm-policy.yml #519 lands.
• marketplace doctor: warn when package dependencies bypass marketplace #847 — marketplace doctor warns when package dependencies bypass
  marketplace. Related supply-chain audit, different axis (governance
  boundary crossing vs. constraint pinning). Coexist cleanly.