Goal
Define and validate the stability contract for module dependency closure.
Background
The current API manifest marks gh as stability: stable and since: 2.0.0, but its current implementation declares process as a dependency. The process module is explicitly stability: preview, since: unreleased, and is not present in the immutable v2.0.0 tree. scripts/api-manifest check validates dependency existence and cycles, while release-check verifies only stable module paths and symbols; neither checks the stability of a stable module's dependency closure. This leaves it ambiguous whether stable gh is consumable as a stable API, whether its dependency must be promoted with it, or whether the module itself should remain preview.
Scope
- Specify whether stable modules may depend on preview/unreleased modules.
- Extend manifest validation and release-check to enforce the chosen policy transitively and report the offending dependency path.
- Align
base_api_manifest.yaml, module READMEs, API reference, and v2 contract documentation with that policy.
- Add a regression fixture for a stable-to-preview dependency and a valid stable closure.
Acceptance Criteria
- The manifest has one unambiguous rule for dependency stability and release availability.
- CI fails before merge when a stable module violates that rule, or the manifest explicitly models a reviewed exception with coverage and release behavior.
- A release-check cannot report a stable API as valid while its required dependency is absent from the referenced release tree.
- Current
gh/process metadata and documentation are made consistent with the selected policy.
Validation
./tests/validate.sh
- Focused
tests/api-manifest.bats coverage for stable/preview dependency closure and release-tree checks.
Non-Goals
- Promoting
process to a stable release as part of this issue.
- Changing the public GitHub helper signatures.
Project Fields
- Status: Backlog
- Priority: P1
- Area: Manifest
- Initiative: Adoption Polish
- Size: S
- Milestone: v2.1.0
Agent Assignment
Goal
Define and validate the stability contract for module dependency closure.
Background
The current API manifest marks
ghasstability: stableandsince: 2.0.0, but its current implementation declaresprocessas a dependency. Theprocessmodule is explicitlystability: preview,since: unreleased, and is not present in the immutablev2.0.0tree.scripts/api-manifest checkvalidates dependency existence and cycles, whilerelease-checkverifies only stable module paths and symbols; neither checks the stability of a stable module's dependency closure. This leaves it ambiguous whether stableghis consumable as a stable API, whether its dependency must be promoted with it, or whether the module itself should remain preview.Scope
base_api_manifest.yaml, module READMEs, API reference, and v2 contract documentation with that policy.Acceptance Criteria
gh/processmetadata and documentation are made consistent with the selected policy.Validation
./tests/validate.shtests/api-manifest.batscoverage for stable/preview dependency closure and release-tree checks.Non-Goals
processto a stable release as part of this issue.Project Fields
Agent Assignment