GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: Quality gates between layers via SOURCES convention

Open
#95 2 comments 1 reaction 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.