marketplace doctor: warn when package dependencies bypass marketplace

[sergio-sisternes-epam]

Problem

When a marketplace author lists packages that have dependencies.apm entries using direct repo paths (e.g. owner/repo/path/to/pkg), those dependencies are resolved at consumer install time via direct git clone -- completely bypassing the marketplace catalogue.

This creates a supply-chain consistency gap:

• The package itself is pinned via the marketplace (specific SHA or version)
• But its transitive dependencies track HEAD of the source repo (mutable, unpinned)

Example

# marketplace.yml - author pins code-quality at a specific SHA
packages:
  - name: code-quality
    source: acme-org/agent-forge
    ref: abc123...
    subdir: agents/code-quality

# code-quality/apm.yml - but its deps use direct paths (not marketplace refs)
dependencies:
  apm:
    - acme-org/agent-forge/general/conventions   # resolves via git, tracks HEAD
    - acme-org/agent-forge/backend/standards      # same issue

The consumer gets code-quality at the pinned SHA, but conventions and standards at whatever HEAD happens to be -- defeating the purpose of marketplace version control.

Proposed solution

1. apm marketplace doctor should add a check: for each package in marketplace.yml, fetch its apm.yml and inspect dependencies.apm. Warn when dependencies use direct repo paths instead of name@marketplace format.

2. Documentation should guide marketplace authors to use marketplace refs in their package dependencies:

   # Before (insecure, tracks HEAD):
   dependencies:
     apm:
       - acme-org/agent-forge/general/conventions
   
   # After (marketplace-resolved, version-pinned):
   dependencies:
     apm:
       - conventions@my-marketplace

Context

Discovered during manual testing of the marketplace maintainer UX (PR #790). The DependencyReference.parse() path for direct repo paths creates a virtual subdirectory package that resolves via git clone, while the parse_marketplace_ref() path for name@marketplace format resolves through the catalogue with proper version pinning.

Related to #722.

[github-actions]

Triage decision

accept

Proposed labels

theme/security
area/marketplace
area/docs-site
type/feature
status/accepted
status/triaged

Milestone

null

Suggested next action

Implement the apm marketplace doctor dependency-bypass check and add marketplace author guidance to the docs.

Suggested issue comment

Thanks for this sharp supply chain catch! The dependency bypass gap -- marketplace-pinned packages whose transitive deps still resolve via direct git clone -- is a real integrity hole.

The proposed `apm marketplace doctor` check is the right fix: it runs at validation time, is non-breaking, and gives marketplace authors a clear signal that their dependency declarations need to switch from direct repo paths to `name@marketplace` format.

A few things to sort out during implementation:
- The check should warn (not fail-hard) on first pass; marketplace authors may have legacy deps that need migration time.
- Output should name the offending package, the dep path, and the suggested `name@marketplace` equivalent so the fix is one edit away.
- The implementing PR should include a new section in the marketplace authoring docs (area/docs-site added as secondary label) to guide authors on using marketplace refs in package dependencies.

Related: #722 (marketplace generate) tracks the broader marketplace UX surface.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The apm marketplace doctor surface is a natural linting/auditing tool familiar from npm audit and cargo check. The user task is clear: marketplace maintainers run doctor to validate their marketplace configuration before publishing. The warn-not-fail approach is correct for a new check. Output should name offending packages and deps concretely. Current labels are authoritative and correct.

Supply Chain Security Expert -- Risk-Surface Reviewer

This addresses a real supply chain integrity gap: marketplace version pinning has a bypass via transitive direct-repo deps that resolve via mutable git clone (tracking HEAD). The theme/security + area/marketplace labeling is correct. The fix adds validation at doctor time without changing install behavior. No new security risk surfaces from the proposed check itself.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- sergio-sisternes-epam is a core collaborator with substantial prior interaction on microsoft/apm; tone-tuning for new contributors is not needed.

Python Architect -- Architecture Reviewer

Not activated -- the feature adds a new validation check to an existing doctor command surface without cross-cutting design decisions or schema changes. The proposed implementation (fetch apm.yml, inspect dependencies.apm, warn on direct-path entries) is straightforward and well-bounded within the marketplace doctor surface.

Doc Writer -- Documentation Reviewer

Docs work is implied: the issue proposes guidance for marketplace authors on switching from direct-path deps to marketplace refs. area/docs-site added as a secondary label so the implementing PR includes the marketplace authoring guide update. The suggested comment wording uses vocabulary grounded in the existing marketplace documentation.

APM CEO -- Triage Arbiter

Clean accept. The issue is well-scoped and addresses a genuine supply chain gap in the marketplace model. Existing labels are authoritative; area/docs-site is the only panel addition. No milestone assigned -- this is a marketplace doctor feature that fits the next minor release cadence rather than the current patch (0.9.4). The warn-at-doctor-time approach is the right conservative first step, leaving install behavior unchanged.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/security",
  "areas": ["area/marketplace", "area/docs-site"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Implement the apm marketplace doctor dependency-bypass check and add marketplace author guidance to the docs.",
  "comment_markdown": "Thanks for this sharp supply chain catch! The dependency bypass gap -- marketplace-pinned packages whose transitive deps still resolve via direct git clone -- is a real integrity hole.\n\nThe proposed apm marketplace doctor check is the right fix: it runs at validation time, is non-breaking, and gives marketplace authors a clear signal that their dependency declarations need to switch from direct repo paths to name@marketplace format.\n\nA few things to sort out during implementation:\n- The check should warn (not fail-hard) on first pass; marketplace authors may have legacy deps that need migration time.\n- Output should name the offending package, the dep path, and the suggested name@marketplace equivalent so the fix is one edit away.\n- The implementing PR should include a new section in the marketplace authoring docs to guide authors on using marketplace refs in package dependencies.\n\nRelated: #722 (marketplace generate) tracks the broader marketplace UX surface."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 1.6M · ◷