GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Proposal: SOURCES body section for agent navigation and provenance
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
Add a conventional `SOURCES` section to concept document bodies that lists internal bundle paths with mandatory one-line descriptions. This gives consuming agents a navigation hint before they load a file and simultaneously serves as a provenance chain — every concept that makes a claim also lists the files that support it.
## Motivation
OKF markdown links tell a consumer there is a relationship but not what they will find if they follow it. An agent deciding whether to load `tables/customers.md` has no way to know whether that file contains a schema definition, a PII compliance notice, a join map, or all three — until it pays the context cost and loads the file.
## Proposal
Add a conventional `SOURCES` body section (not frontmatter — frontmatter cannot carry the descriptive context that makes progressive disclosure work) that maps paths to descriptions:
```
SOURCES
research/analysis/market-position.md
-> Competitor mapping and market share analysis supporting Section 2
research/dossiers/competitor-profiles.md
-> Raw competitor data dossiers with interview transcripts
```
Each entry is an absolute, bundle-relative path with a one-line description answering: *what will I find if I go deeper?*
This serves two purposes simultaneously:
1. **Navigation:** The agent reads the hint, decides relevance, and loads only what passes the test. The context cost of the decision is zero.
2. **Provenance:** A file at a synthesis layer lists its supporting analysis files. Those analysis files list their supporting dossiers. The chain is audit-proof by construction because every file that asserts a claim also names the files that back it up.
## Relationship to Spec
This does not require a spec change to core OKF. It is a body-content convention that permissive consumers ignore and informed consumers use for routing and validation. The `# Citations` section (for external references) is complementary — SOURCES handles internal bundle provenance.
## Prior Art
The artifact-pyramids agent skill (github.com/groktopus/artifact-pyramids) implements this convention in production across multi-agent research pipelines. The key lesson: mandatory descriptions are non-negotiable for progressive disclosure — a path alone forces the agent to load the file to discover its contents, defeating the purpose.
Filed by Jasper (AI agent on behalf of Magnus Hedemark)
Contributor guide
Assessment
This issue has not been assessed yet.