holocron/docs/adr/0026-a-plugin-package-is-not-an-install-root.md

A plugin package is not an install root — apm-audit-ci waives lockfile-exists for one

Status: Accepted (2026-09-20)

plugins/onedev is the first plugin package in this repo to declare a real dependency. It pins code.onedev.io/onedev/tod#v4.3.4 so that a consumer installing onedev from the holocron marketplace picks up OneDev's eight TOD skills transitively — a marketplace.packages entry takes a local source: path, so a third-party repo cannot be listed for redistribution on its own, and the wrapper is the only mechanism that carries it.

That arms a check every previous plugin left vacuous, and leaves the package with no green state.

apm audit --ci in a plugin directory runs one check, lockfile-exists. While every plugin apm.yml declared dependencies: {apm: [], mcp: []} it reported No dependencies declared -- lockfile not required and passed. plugins/onedev declares dependencies, so (verified against apm 0.28.0):

• without a package apm.lock.yaml it fails — apm.yml declares dependencies but apm.lock.yaml is absent, reported as 1 of 1 check(s) failed
• with one it passes, and passing arms the other nine checks. drift then fails reporting eight unintegrated files at .agents/skills/<name>/SKILL.md — it wants the dependency's skills deployed inside the package. Generating the lockfile with apm lock also creates an apm_modules/ tree in there.

The cause is that apm treats any directory holding both apm.yml and apm.lock.yaml as an install root. A plugin package is not one: it is content to be installed somewhere else. The second state is not a stricter version of the first, it is a category error — a package has no deployment target of its own, so there is nothing for a drift check to be right about.

The hook therefore waives lockfile-exists, and only that, for a non-root manifest. scripts/apm-audit-ci.sh replaces the inline bash -c loop that .pre-commit-config.yaml carried. The waiver fails closed on three axes: the root manifest is never waived whatever it reports; the failing check must be lockfile-exists and no other, asserted by matching 1 of 1 check(s) failed, so any second failing check changes the count and fails the push normally; and output apm does not produce in the recognised shape is a failure.

Dropping --ci for package directories was rejected. It was the smaller change — plain apm audit in a plugin directory reports No apm.lock.yaml found -- nothing to scan and exits 0, so the loop would have gone green with a one-word edit. It is wrong. Verified on apm 0.28.0 against a scratch package whose dependency entry carried no git/path/registry field: apm audit --ci exits 1 naming the missing field, while plain apm audit exits 0 and says nothing. Malformed- dependency detection is the reason docs/spec/gates.md gives for auditing packages at all, and a package with dependencies is the only kind that can carry a malformed dependency entry — so the cheap fix would have discarded the check precisely where it earns its keep, in the one package that newly needs it.

Two alternatives were rejected for making the wrapper pointless or the repo fragile. Dropping the dependency from plugins/onedev turns the gate green immediately, but a consumer installing onedev from the marketplace then receives an empty package, which removes the only reason the wrapper exists. Committing a package lockfile and running apm install inside the package satisfies drift on a machine that has done so, but makes deployed-files-present a fresh-clone failure and commits this repo to maintaining a nested install root per package.

The weak point is stated rather than designed away: the waiver matches on apm's stdout, so an apm upgrade that rewords either line silently turns it off. That direction is safe — it fails the push rather than hiding a defect. Re-verify against the new output and update the two patterns rather than widening them.

This changes shared enforcement, which is why it is recorded here rather than left as a comment. docs/spec/gates.md's apm-audit-ci section carries the operative detail.