feat(spec): publish OpenAPM v0.1 as a single normative specification document

[danielmeppiel]

Context

APM today documents its core data formats and protocols as separate reference pages in docs/src/content/docs/reference/:

• manifest-schema.md — apm.yml package manifest
• lockfile-spec.md — apm.lock.yaml resolution lockfile
• policy-schema.md — apm.policy.yml governance policy
• registry-http-api.md — package registry HTTP contract
• primitive-types.md — skill/agent/chatmode/instruction/MCP/hook primitive types
• package-types.md — package, plugin, marketplace
• targets-matrix.md — target compatibility surface

These pages are user-facing documentation. They are NOT normative: they describe behavior in prose, mix examples with rules, do not version-pin, and do not state conformance requirements. As third parties begin to integrate against APM data formats (e.g., JFrog Artifactory via #1471, Claude-Code-compatible marketplaces via #1422), the lack of a single normative reference becomes a liability — integrators have no version-anchored document to pin against, and APM has no stable contract to evolve under semver.

This issue tracks publishing OpenAPM v0.1: one normative specification document that consolidates the above into a single, conformance-grade artifact suitable for external integrators to pin against.

Goal

A single document at docs/src/content/docs/specs/openapm-v0.1.md (or docs/specs/openapm-v0.1.md, maintainer's call) that:

1. Normatively defines the four data formats and one protocol APM exposes:
   • Manifest format (apm.yml)
   • Lockfile format (apm.lock.yaml, currently schema v2)
   • Policy format (apm.policy.yml)
   • Registry HTTP API (resolve / fetch contract)
2. Normatively defines the dependency-resolution semantics: ref kinds (registry / git / marketplace / local), semver ranges, tag-pattern resolution, transitive resolution, conflict resolution, lockfile replay.
3. Normatively defines the primitive type system and target compatibility matrix.
4. Uses RFC 2119 / 8174 keyword conventions (MUST / SHOULD / MAY).
5. Is version-pinned as v0.1, with an explicit forward-compatibility and amendment process.
6. Has its own CI-enforced consistency check against the implementation (see "Conformance" below).
7. Is MIT-licensed in line with the rest of microsoft/apm.

Non-goals

• Not a rewrite of the existing reference pages. Those remain as non-normative companions (user-friendly explanations) and link to the spec for normative statements.
• Not a new JSON Schema generator. Existing schemas (tests/fixtures/schemas/, runtime validators) remain the source of truth for machine validation; the spec references them.
• Not v1.0. v0.1 explicitly signals editor's-draft status under semver-zero.

Suggested structure

1. Introduction
2. Conformance (RFC 2119 keywords, conformance classes: producer / consumer / registry / governance)
3. Terminology
4. Data formats
   4.1 Manifest (apm.yml)
   4.2 Lockfile (apm.lock.yaml)
   4.3 Policy (apm.policy.yml)
5. Primitive type system
6. Target compatibility
7. Dependency resolution
   7.1 Reference kinds
   7.2 Semver and tag patterns
   7.3 Transitive resolution
   7.4 Lockfile semantics
8. Registry HTTP API
9. Versioning and amendment process
10. Security considerations
11. Appendix A: Normative JSON Schemas (by reference)
12. Appendix B: Compatibility with Claude-Code marketplace plugin schema

In scope of v0.1

The spec must reflect the state of the implementation as of the merge of these in-flight PRs:

• feat(deps): resolve semver ranges on git-source dependencies #1496 (Theme 1) — git-source semver resolution + lockfile constraint / resolved_tag / resolved_at fields
• feat(pack): --create-tag and --push to materialize release tags (#1489) #1497 (Theme 4) — pack release-tag automation
• feat(deps): add 'apm deps why <pkg>' to explain transitive dependencies #1495 (Theme 2) — apm deps why (consumer-facing; surface only)
• feat(policy): require_pinned_constraint to ban unbounded dep ranges #1494 (Theme 3) — policy.dependencies.require_pinned_constraint

These should be merged first, then folded into the spec as part of this work.

Conformance check (CI)

The spec must not silently drift from the implementation. Proposed mechanism (maintainer may refine):

• A tests/spec/test_openapm_v0_1_conformance.py that loads the spec, extracts every normative MUST/SHOULD statement tagged with a fixture, and verifies the implementation honors it.
• A scripts/check-spec-references.sh that asserts every JSON Schema referenced in Appendix A exists and parses.
• A docs build check that flags any reference page making a normative claim that contradicts the spec.

Success criteria

• docs/specs/openapm-v0.1.md exists, MIT-licensed, version-pinned v0.1.
• All four in-scope PRs merged and reflected.
• RFC 2119 / 8174 keyword usage throughout.
• Each normative requirement has either an explicit conformance test or an explicit fixture link.
• Existing reference pages updated to defer normative claims to the spec and explicitly state their non-normative status.
• CI conformance check green.
• One worked example per conformance class (producer / consumer / registry / governance) demonstrating end-to-end compliance.

Out of scope (track separately)

• Translations.
• Schema validators in other languages (Go / Rust / TypeScript binding) — separate issues.
• Submission to external standards bodies — separate decision.

Skills required

This is spec-editor work, not implementation work. The right contributor profile:

• Has edited at least one published normative specification (IETF RFC, W3C Rec, or equivalent).
• Comfortable with RFC 2119 keyword discipline and conformance-test methodology.
• Reads Python well enough to verify spec vs. implementation but is not expected to refactor apm_cli/.
• Understands semver and dependency-resolution algorithms (Cargo / npm / Go modules background welcome).

Estimated scope

Editor-draft (~2-4 weeks of focused work for an experienced spec editor). Not a weekend issue.

References

• RFC 2119 (Key words for use in RFCs)
• RFC 8174 (Ambiguity of uppercase vs lowercase in RFC 2119 key words)
• Existing reference pages listed above
• In-flight PRs: feat(policy): require_pinned_constraint to ban unbounded dep ranges #1494, feat(deps): add 'apm deps why <pkg>' to explain transitive dependencies #1495, feat(deps): resolve semver ranges on git-source dependencies #1496, feat(pack): --create-tag and --push to materialize release tags (#1489) #1497
• Related issues: feat(deps): resolve semver constraints on git-source dependencies against repo tags #1488, feat(pack): --create-tag and --push flags to create and push release tag after --check-versions #1489, feat(deps): apm deps why <pkg> - explain why a transitive dependency was installed #1490, feat(policy): add dependencies.require_pinned_constraint to ban unbounded ranges #1491