GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Proposal: Quality gates between layers via SOURCES convention
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
Adopt a convention that concept files at the `analysis` layer MUST include a SOURCES body section pointing to at least one file at the `concept` or `dossier` layer. Files at the `synthesis` layer MUST include a SOURCES section pointing to at least one `analysis` file. This creates directional quality gates between layers — a claim cannot move up the hierarchy without evidence beneath it.
## Motivation
OKF's permissive consumption model accepts any content at any quality level. This is the right policy for an interchange format, but it provides no guidance for production pipelines that need to verify knowledge quality before routing it downstream. Without quality gates, there is no structural distinction between a well-supported analysis and an unsupported assertion.
## Proposal
Adopt a layered quality gate convention enforced by the SOURCES section:
- A file with `layer: concept` or `layer: dossier` has no upward provenance requirement (it IS the evidence)
- A file with `layer: analysis` MUST have a SOURCES section listing at least one file at `concept` or `dossier` layer
- A file with `layer: synthesis` MUST have a SOURCES section listing at least one file at `analysis` layer
The gate criteria are specific and falsifiable: every summary claim links to an analysis file, every analysis claim links to a dossier, every dossier has a source URL or transcript. A claim that cannot trace to evidence at the layer beneath it does not move up.
## Relationship to Spec
This is a production convention, not a spec requirement. It depends on the layer field (issue #93) and SOURCES section (issue #92) to function. Permissive OKF consumers ignore the gates entirely. Pipeline orchestrators use them to validate routing contracts before delivering bundles to downstream agents.
## Prior Art
The artifact-pyramids agent skill (github.com/groktopus/artifact-pyramids) enforces these gates in production. The mechanism is structural, not procedural: a summary file whose SOURCES section references L2 files that do not exist yet is structurally incomplete. The gate is enforced by the SOURCES convention itself, not by a separate validation pass.
Filed by Jasper (AI agent on behalf of Magnus Hedemark)
Contributor guide
Assessment
This issue has not been assessed yet.