Contracts outside contracts/index.yaml — classification (2026)
Contracts outside contracts/index.yaml
Section titled “Contracts outside contracts/index.yaml”contracts/index.yaml is the preferred machine inventory for maintained artifacts (owner, enforced_by, kind).
Many paths under contracts/ are intentionally not indexed:
| Class | Examples | Policy |
|---|---|---|
| Generated / snapshot reports | contracts/reports/** JSON | Do not treat as hand-edited SSOT; prune only when no CI consumer reads them |
| Derived registries | contracts/cli/command-registry.yaml, contracts/mcp/tool-registry.canonical.yaml, contracts/capability/capability-registry.yaml | Edit contracts/operations/catalog.v1.yaml then vox ci operations-sync |
| Nested schema siblings | JSON Schema next to a parent YAML named in the index | Owned by the same id as the parent row where obvious |
| Fixture / eval payloads | Large matrices under contracts/eval/** | Add an index row when a CI job treats them as authoritative |
When to add an index row
Section titled “When to add an index row”Add a row when any of these hold:
- A
vox ci *guard reads the file path literally. - Human docs call the file “SSOT” without pointing at a parent catalog.
- The file defines new
VOX_*env vars or persistent Tier A shapes.
Version header vs filename
Section titled “Version header vs filename”Some files use *.v1.yaml with x-vox-version > 1. Treat x-vox-version as semantic contract version; filename suffix is legacy. Renames are backlog items — see legacy remediation ledger.