Validate the Complete Shipped Catalogue in CI¶
Status¶
Accepted: Every shipped module and blueprint is discovered from the repository tree and validated as one catalogue before Core can be packaged or released.
Context¶
Focused tests can pass while a newly added contract remains malformed, misnamed, incomplete, or disconnected from the catalogue. Manually maintained test lists also allow new modules and blueprints to avoid the release gate.
The shipped surface is defined by repository paths: module spec.yml files and
blueprint manifests. Catalogue validation must therefore discover those files
rather than depend on a second list.
Decision¶
The shared Core quality workflow recursively validates every shipped module specification and blueprint manifest.
For modules, the gate requires parseable YAML, ModuleSpec identity, a
directory-matching module_ref, a complete execution binding, a README, and at
least one example file. For blueprints, it requires schema validity, a
directory-matching blueprint_ref, and resolvable module references for normal
and archive lifecycle steps.
The same quality workflow gates pull-request CI and release packaging. The documentation generator derives public module and blueprint indexes from the same repository surface.
Consequences¶
Positive¶
- A new catalogue entry cannot bypass validation by being omitted from a list.
- Broken references fail before release artifacts are built.
- Public indexes and source counts derive from the shipped contract tree.
Negative¶
- Every module must carry its reviewable companion documentation and example.
- A malformed contract blocks the complete quality job until corrected.
Alternatives considered¶
- Validate only changed paths: rejected because cross-reference and packaging defects can involve unchanged catalogue entries.
- Maintain a separate catalogue manifest: rejected because it creates another source that can drift from the shipped tree.