Plugin bundles should embed apm.lock.yaml (supply-chain integrity + restores apm pack/unpack round-trip)

[danielmeppiel]

Updated after devx-ux review. Original framing (just "ship the lockfile, extend unpack mapping") was too narrow. The cleaner unification: apm unpack shouldn't exist as a separate verb. Plugin bundles are pre-resolved packages; apm install already knows how to integrate those into a project. This issue now proposes that direction. Original problem statement preserved below for context.

TL;DR

1. Supply-chain: plugin bundles ship no apm.lock.yaml, so they have no embedded SBOM / integrity manifest / provenance. Add it.
2. Mental model: a plugin bundle IS a pre-resolved package. apm install already knows how to route a package's flat skills//agents//commands//instructions/ layout to the correct target tree. Make apm install accept a local plugin bundle (file or directory). This is what pip install ./foo.whl, cargo install --path ., and npm install ./pkg.tgz already do.
3. Deprecate apm unpack (and the apm bundle format) over two release cycles. Single canonical bundle format = plugin. Single canonical entry point = install.
4. Round-trip restored as a free side effect.

Background (verified empirically against apm HEAD 0.11.0, commit 2b9501ab)

• apm pack default flipped from apm to plugin format in 0.11.
• plugin bundle: <root>/plugin.json + flat skills/<slug>/SKILL.md, agents/<name>.md, commands/<name>.md, instructions/<file>. No apm.lock.yaml -- explicitly excluded at src/apm_cli/bundle/plugin_exporter.py:140-155.
• apm bundle: <root>/.github/<kind>/<slug>/<file> (target-deployed paths) + apm.lock.yaml whose deployed_files drives apm unpack.
• apm unpack <plugin.tar.gz> exits 1 with apm.lock.yaml not found. Default pack -> unpack round-trip is broken in 0.11+ unless the user passes --format apm.
• microsoft/apm-action PR Refactor prompt integration and add agent integration #31 currently defends downstream by defaulting bundle-format: apm and rejecting plugin tarballs at restore.

Why "ship the lockfile" alone isn't the right framing

LockedDependency (src/apm_cli/deps/lockfile.py:20-50) records repo_url, resolved_commit, resolved_ref, version, deployed_files, deployed_file_hashes, content_hash, is_insecure, discovered_via. It is already an SBOM + integrity manifest. Excluding it from plugin bundles means:

• No tamper evidence -- a plugin bundle modified post-pack is indistinguishable from the legitimate one.
• Not reproducible -- third parties cannot re-resolve from sources and verify they get the same artifact.
• No machine-readable dep graph for scanners -- CVE/license/policy tooling cannot operate on the artifact.
• Inconsistent with project posture -- APM enforces lockfile-frozen installs, hash verification, and content-security scanning everywhere else.

So the lockfile must be in plugin bundles for supply-chain reasons, full stop. (Precedent: pip RECORD, cargo shipping Cargo.lock in source crates, OCI manifests with layer digests, SLSA provenance, CycloneDX/SPDX SBOMs.)

But shipping the lockfile is not the way to fix unpack, because that path keeps two parallel verbs (install + unpack), two parallel bundle formats (apm + plugin), and two parallel routing-mapping codepaths. The integration pipeline that apm install already runs is exactly the logic unpack should be calling.

Proposed direction: unify on apm install

A plugin bundle is a pre-resolved package with an integration-ready flat layout. The existing apm install pipeline already:

• Routes skills/, agents/, commands/, instructions/ to the correct target tree (.github/, .claude/, .gemini/, .cursor/, ...).
• Applies the canonical naming convention.
• Honors --target <t1,t2,...> for multi-target deploys.
• Detects collisions via BaseIntegrator.check_collision() (skips locally-modified files unless --force).
• Supports --dry-run.

All of this should "just work" if apm install accepts a local bundle:

apm install ./bundle.tar.gz             # detect plugin.json -> treat as pre-resolved
apm install ./bundle-dir/               # same, directory form
apm install owner/repo                  # remote, full resolution (today's behavior)

This matches what pip/cargo/npm already do, eliminating an APM-specific verb users have to learn.

Concrete behavior

1. Detection: apm install <local-path> checks for plugin.json at root. If present, treat the path as a pre-resolved package and skip dependency resolution.
2. Lockfile: read embedded apm.lock.yaml (after change 1 below). Use it for provenance verification (hash check on each file, integrity check on content_hash) -- NOT for routing. This is a semantic inversion of the lockfile's role inside a bundle (today: routing manifest; tomorrow: SBOM/integrity).
3. Routing: hand off to the same integrator pipeline apm install owner/repo already runs. --target resolves identically (auto-detect from apm.yml or workspace; explicit --target a,b for multi-target).
4. Naming: derive the package identifier for the -<package> suffix from plugin.json:id. Fallback: bundle dirname. Error if neither resolves. Add --as <alias> to override (matching the existing owner/repo@alias pattern).
5. Collisions: inherit install's collision behavior (skip locally-modified files unless --force). Print skip count + remediation:

   [!] 3 files skipped (locally modified). Use --force to overwrite.
       .github/instructions/coding-style.md
       .claude/agents/reviewer.md
       .cursor/rules/linting.md
   

6. Offline guarantee: apm install <local-path> must do zero network I/O when the source is a local file. Verify the integrator codepath has no implicit network calls (link resolution, marketplace lookups). The current apm unpack is fully offline; that property must be preserved when migrating bundles to install.

Coordinated changes required

Change 1 -- ship apm.lock.yaml in plugin bundles. Drop it from the exclusion list in _collect_root_plugin_components and per-dependency walker (plugin_exporter.py:140-155). Place at <bundle-root>/apm.lock.yaml. Claude Code consumers ignore it. Bundle gains a verifiable SBOM at no behavioral cost.

Change 2 -- apm install accepts local bundle paths. Detect plugin.json at root, route through the existing integrator pipeline, verify against embedded lockfile.

Change 3 -- embed pack-time target metadata for round-trip fidelity. A bundle packed with --target copilot,claude and re-installed in a project that auto-detects only copilot would silently drop the claude artifacts. Embed the original --target set in plugin.json (or apm.lock.yaml) and have install warn:

[!] Bundle was packed for [copilot, claude]. Current resolved target is [copilot].
    Use --target copilot,claude to restore the full layout.

Change 4 -- deprecate apm unpack and the apm bundle format. Suggested timeline:

Release	apm install <bundle>	apm unpack <bundle>	--format apm
v0.12	works on plugin bundles via integrator	thin alias -> install; deprecation notice	works; no notice
v0.13	unchanged	deprecation notice	deprecation notice
v0.14 or v1.0	unchanged	removed	removed

Two release cycles is reasonable for a pre-1.0 tool.

Footguns / blind spots called out

• Lockfile role inversion (today: routing; tomorrow: provenance) needs explicit documentation so reviewers and downstream tools don't assume routing semantics.
• Air-gapped installs must remain network-free; integrator codepath needs an audit before unifying.
• Round-trip fidelity requires embedding target-set metadata in the bundle (Change 3).
• Behavior migration for users of today's apm unpack: file layout was bundle-baked; with the new path it becomes target-resolved. Migration notes should call this out explicitly.

Downstream impact

• microsoft/apm-action PR Refactor prompt integration and add agent integration #31: defensive bundle-format: apm default and plugin-rejection error stay useful as defense-in-depth until v0.13. After v0.14, action can drop both and let bundle-format follow upstream default.
• gh-aw workflows that round-trip via apm pack + apm unpack are silently broken on 0.11+ today; fixed once Change 2 lands.
• CI integrity gates: workflows can verify bundle provenance from the embedded lockfile. Capability does not exist today on plugin bundles.

Suggested labels

type/feature, theme/security, theme/portability, area/package-authoring, status/needs-triage

References

• Plugin exporter exclusion list: src/apm_cli/bundle/plugin_exporter.py:140-155
• LockedDependency schema: src/apm_cli/deps/lockfile.py:20-50
• Empirical reproduction + downstream defense: microsoft/apm-action#31
• Related downstream issue: microsoft/apm-action#24 (setup-only) -- separate but driven by the same hardening pass.

---

Original framing (preserved for history)

Original draft proposed extending the lockfile schema (deployed_files: list[{bundle, deployed}]) so apm unpack could route plugin bundles via lockfile mapping. devx-ux review pushed back: that keeps two parallel verbs and two parallel formats. The unified-on-install direction above is strictly cleaner, matches package-manager precedent (pip/cargo/npm), and the schema extension is unnecessary because the integration pipeline already knows how to route flat plugin layouts.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/security
theme/portability
area/package-authoring
area/lockfile
type/feature
status/needs-design

Milestone

null

Suggested next action

Draft a short design note (can be a comment here) resolving three questions: (1) does LockedDependency.deployed_files change shape universally or only in the bundle writer; (2) precisely define the back-compat shim for old list[str] lockfiles in both apm unpack and apm install; (3) declare the lockfile placement path in plugin tarballs as a stable contract.

Suggested issue comment

Thank you for this thorough writeup -- the supply-chain gap and the round-trip regression are both real and the proposed direction is sound.

The panel is marking this `status/needs-design` rather than directly accepted because the core schema change (extending `LockedDependency.deployed_files` from `list[str]` to a struct carrying both bundle-relative and deploy paths) has an ambiguous scope that must be resolved before code can land safely:

1. **Schema scope**: Should `deployed_files` change shape universally in `apm.lock.yaml`, or should the plugin bundle writer serialize a different layout without touching the canonical project lockfile schema? A universal change means all existing lockfiles need a migration; a bundle-only change keeps the canonical schema stable but means the bundle and the project lockfile diverge in structure.

2. **Back-compat read path**: The shim that tolerates old `list[str]` shape needs to be precisely specified -- specifically, whether `apm unpack` and `apm install` both get the shim or only `apm unpack`.

3. **Bundle layout contract**: Placing `apm.lock.yaml` at the tarball root (`/apm.lock.yaml`) needs to be declared as a stable, versioned contract so downstream consumers (apm-action, CI scripts, CVE scanners) can rely on it without future breakage.

The supply-chain motivation is strong and aligns with APM's security posture -- lockfile-frozen installs, hash verification, and content-security scanning are already enforced; shipping plugin bundles without their integrity manifest is an outlier. Once the design questions above are resolved (a comment here is sufficient), this can move directly to `status/accepted`.

Suggested next step: add a comment here addressing the three design questions above. The implementing PR can then reference this thread as the settled design record.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The default apm pack -> apm unpack round-trip is silently broken in 0.11+ -- the failure surfaces only at apm unpack time with [x] apm.lock.yaml not found in the bundle, which names what failed but not why (the user has no signal at pack time that plugin format disables unpack). This is a concrete UX regression against the npm pack / cargo package mental model where the default artifact format is always round-trippable. The proposed fix (embed lockfile, teach unpack about plugin layout) directly restores the expected mental model. The UX case for accept is strong; the only open question is implementation design, which the Architect addresses.

Supply Chain Security Expert -- Risk-Surface Reviewer

This is a direct supply-chain risk surface. Plugin bundles without apm.lock.yaml have no tamper evidence, are not reproducible, and cannot be consumed by CVE scanners or policy engines -- all of which contradict APM's stated security posture. The lockfile already contains resolved_commit, deployed_file_hashes (SHA-256 per file), content_hash, is_insecure, and allow_insecure -- it IS the SBOM. Including it at bundle-pack time closes the gap at near-zero behavioral cost to Claude Code consumers (the lockfile is simply ignored by the plugin consumer). Both theme/security (primary) and theme/portability (round-trip restore) are warranted. area/lockfile is required alongside area/package-authoring.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a COLLABORATOR with deep domain knowledge; tone-tuning for a new contributor is not warranted.

Python Architect -- Architecture Reviewer

The proposed Option A (schema change to LockedDependency.deployed_files: list[str] -> list[{bundle: str, deployed: str}]) is cross-cutting: it touches lockfile.py (schema + reader shim), plugin_exporter.py (writer), apm unpack path, and any test fixtures that serialize lockfiles. The change is feasible and the back-compat shim is straightforward, but the schema scope is ambiguous -- a bundle-relative path field only makes semantic sense inside a bundle, not in a regular project lockfile. If the struct is added universally, the project lockfile gains a field (bundle) that is meaningless outside a bundle context. The cleanest resolution is a bundle-only serialization: the canonical lockfile schema stays list[str], and the bundle writer injects a sidecar mapping file (e.g., apm.lock.bundle.yaml) that records the bundle-relative paths without touching the canonical schema. This avoids a migration entirely. The issue as written does not settle this; it should before implementation starts, hence status/needs-design.

Doc Writer -- Documentation Reviewer

An implementing PR will need updates to: docs/src/content/docs/reference/cli-commands.md (apm pack behavior change), docs/src/content/docs/reference/lockfile-spec.md (if schema changes), docs/src/content/docs/enterprise/security.md (plugin bundles now carry a verifiable SBOM), and packages/apm-guide/.apm/skills/apm-usage/commands.md (Rule 4). The area/docs-site label was considered but pruned to stay within the 6-label cap; the implementing PR should carry it. The author's wording is precise and uses canonical APM vocabulary throughout.

APM CEO -- Triage Arbiter

The supply-chain gap is real and strategically significant -- APM's positioning as the secure package manager for AI-native development is weakened if its default artifact format lacks a verifiable integrity manifest. The Python Architect has correctly identified that the schema migration boundary is under-specified, making direct accept premature. needs-design is the right call: the direction is accepted, the design questions are bounded and answerable in a single comment thread, and the implementing PR can proceed immediately once they are settled. No milestone is assigned per the needs-design rule; priority is withheld for the same reason.

{
  "decision": "needs-design",
  "decision_detail": "Schema scope of LockedDependency.deployed_files change (universal vs bundle-only), back-compat shim specification, and bundle layout contract must be settled before implementation.",
  "theme": "theme/security",
  "areas": ["area/package-authoring", "area/lockfile"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Draft a design comment here resolving: (1) universal vs bundle-only schema change, (2) back-compat shim scope for apm unpack and apm install, (3) stable bundle layout contract for /apm.lock.yaml.",
  "comment_markdown": "Thank you for this thorough writeup -- the supply-chain gap and the round-trip regression are both real and the proposed direction is sound.\n\nThe panel is marking this `status/needs-design` rather than directly accepted because the core schema change (extending `LockedDependency.deployed_files` from `list[str]` to a struct carrying both bundle-relative and deploy paths) has an ambiguous scope that must be resolved before code can land safely:\n\n1. **Schema scope**: Should `deployed_files` change shape universally in `apm.lock.yaml`, or should the plugin bundle writer serialize a different layout without touching the canonical project lockfile schema?\n\n2. **Back-compat read path**: The shim that tolerates old `list[str]` shape needs to be precisely specified -- specifically, whether `apm unpack` and `apm install` both get the shim or only `apm unpack`.\n\n3. **Bundle layout contract**: Placing `apm.lock.yaml` at the tarball root needs to be declared as a stable, versioned contract so downstream consumers can rely on it.\n\nThe supply-chain motivation is strong and aligns with APM's security posture. Once the design questions above are resolved (a comment here is sufficient), this can move directly to `status/accepted`.\n\nSuggested next step: add a comment here addressing the three design questions above."
}

---

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.

Note

🔒 Integrity filter blocked 19 items

The following items were blocked because they don't meet the GitHub integrity level.

• #1013 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #888 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #876 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #844 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #820 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #805 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #801 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #799 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #797 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #765 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #751 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #744 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #732 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #690 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #650 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• #645 search_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
• ... and 3 more items

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Triage Panel for issue #1098 · ● 844.9K · ◷