The spec corpus — finding the golden state for your ticket
Before you can close a gap you have to know which spec owns the behavior. The corpus is ~100+ markdown specs spread across developers-environment and the component repos, organized in three tiers.
Three tiers
| Tier | Governs | Lives at | Example id |
|---|---|---|---|
| platform | a cross-product service contract or platform-wide convention | developers-environment/specs/platform/ |
platform.spec-governance |
| product | a domain object end-to-end, across services | developers-environment/specs/products/ |
product.lens |
| component | one repo's behavior | <repo>/specs/ |
component.oracle.apollo |
A repo's golden state is the union of the dev-env specs that touch it and its own
<repo>/specs/ suite — never dev-env alone. Most component repos carry a substantial local
suite.
Identity: the id, never the path
Every spec is addressed by its frontmatter id (tier.owner.name). Files move and get renamed;
ids don't. The registry specs/INDEX.yaml (generated — never hand-edit) resolves every id to
its home, and sections are addressed by stable heading anchors:
## Lifecycle <!-- #lifecycle -->
so product.lens#lifecycle names exactly one section, forever, regardless of retitles. The id
grammar, anchor rules, and validation gate (build_spec_index.py --check) are specified in
platform.spec-governance — and the conventions for writing a good spec are in the
spec writing guide.
Finding the spec for your ticket
- Ticket names an id or section (
product.lens#lifecycle)? You're done — resolve it viaspecs/INDEX.yaml. - Ticket names a domain object (Lens, TrainedModel, Block)? Start at the product tier.
- Ticket is about one service's behavior? Enumerate that repo's
specs/*.mdfirst — don't reflexively reach for a dev-env spec. - Nothing covers it? That's not a dead end — it's Shape 1 in the next page: the spec edit comes first.
What you can do now
- Resolve any spec id to its file: look it up in
specs/INDEX.yaml. - For your ticket, name the governing tier and spec — or conclude, defensibly, that no spec covers it yet.