Document downstream registry consumer contract

[SoundBlaster]

Motivation

Downstream projects consume the same public /v0 registry surface, but the shared consumer contract was still too implicit. SpecGraph, ContextBuilder, SpecNode, and lab deploy checks need a common way to cite registry evidence, classify drift/failures, and avoid turning SpecPM metadata into resolver or runtime authority.

Goals

• Define normative /v0 endpoint classes for downstream registry claims.
• Document minimum evidence fields that consumers should preserve in review artifacts and diagnostics.
• Standardize failure vocabulary for unavailable registries, unsupported API versions, malformed payloads, missing subjects, lifecycle policy, drift, and inconclusive evidence.
• Keep policy, graph interpretation, candidate selection, artifact generation, job execution, archive acquisition, and package content execution outside SpecPM core.

Changes

• Expanded specs/DOWNSTREAM_REGISTRY_CONSUMER_GUIDE.md with contract summary, endpoint classes, evidence envelope, failure semantics, and per-consumer obligations.
• Added DocC page DownstreamRegistryConsumers and linked it from the overview, SpecGraph integration, and registry observation reports pages.
• Updated README, roadmap, workplan, specpm.yaml, and specs/specpm.spec.yaml to expose the downstream consumer contract as part of the self-spec.
• Added regression coverage for the guide, DocC page links, self-spec capability/evidence binding, and roadmap/workplan status.

Validation

• pytest tests/test_core.py -k "downstream_registry_consumer_guide or specgraph_registry_observation_contract or registry_observation_reports or current_roadmap"
• make format-check
• make lint
• make test
• make pages-smoke

Boundaries and Non-Goals

• Does not change public-index generation, accepted packages, registry payload schemas, Docker deployment, Pages deployment workflow, or SFTP deployment workflow.
• Does not add specpm publish, request-time registry mutation, package installation, archive acquisition, package execution, semantic search, graph authority, or runtime policy enforcement.
• make pages-smoke validates the currently deployed /v0 registry surface; the new DocC page is expected to be rendered by the PR DocC build check.

Notes

• The next planned task after this PR is the remote package acquisition design boundary.

[Copilot]

Pull request overview

This PR documents a shared downstream contract for consuming SpecPM’s public /v0 registry evidence without expanding SpecPM into resolver, graph, or runtime authority.

Changes:

• Adds a downstream registry consumer guide with endpoint classes, evidence expectations, failure vocabulary, and consumer boundaries.
• Adds and links a DocC page for downstream registry consumers.
• Updates self-spec metadata, roadmap/workplan status, README references, and regression assertions.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_core.py	Adds regression checks for guide content, DocC links, self-spec bindings, and roadmap/workplan status.
specs/WORKPLAN.md	Marks the downstream registry consumer contract phase complete.
specs/specpm.spec.yaml	Adds capability, evidence, and implementation bindings for the contract.
specs/DOWNSTREAM_REGISTRY_CONSUMER_GUIDE.md	Expands the canonical downstream consumer contract.
specpm.yaml	Exposes the new capability in the package manifest.
Sources/SpecPM/Documentation.docc/SpecPM.md	Links the new DocC page from the overview.
Sources/SpecPM/Documentation.docc/SpecGraphIntegration.md	Cross-links the downstream consumer contract.
Sources/SpecPM/Documentation.docc/Roadmap.md	Updates roadmap status and next planned sequence.
Sources/SpecPM/Documentation.docc/RegistryObservationReports.md	Links observation reports to the consumer contract.
Sources/SpecPM/Documentation.docc/DownstreamRegistryConsumers.md	Adds the public DocC summary page.
ROADMAP.md	Updates roadmap status and removes the completed item from next steps.
README.md	Points readers to the expanded consumer guide.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.