Most enterprises hold far more data than they can safely use. The data is hard to discover, ambiguously modelled, of unknown provenance, and of unclear legal standing. These problems are old, but AI changes their cost: an analyst who meets a badly modelled table asks a colleague, while an AI agent answers anyway, at machine speed, to whoever is on the other end.
astro is an open-source framework for making enterprise data safely usable by humans, applications, and AI agents, and for proving afterwards that it was. It defines what "AI-ready" means in testable terms, how usage rights follow data into derivatives (chunks, embeddings, indexes, caches), how each access path gets a real enforcement point, and what evidence must exist when an auditor asks what an agent saw and who allowed it.
It is written for regulated enterprises (a bank is the reference case), vendor-neutral, grounded in open standards (ODCS, DCAT, ODRL, OpenLineage, AuthZEN, OAuth, SPIFFE, OpenTelemetry, MCP), and intended to stand up to review by Legal, Security, Privacy, Risk, and Audit.
Licence: documentation CC BY 4.0 · tooling MIT · LICENSE.md
A catalogue does not make data AI-ready, and a rights label is not an access control. The framework is organised around four steps. What is true about the data is declared (meaning, grain, temporal guarantee, usage rights) rather than inferred. Every specific use is decided at request time: permit or deny, with a reason. That decision is enforced on every path to the data, including the paths that reach chunks, embeddings, and caches. And everything that happened can be proved afterwards. The rest of the repository is the detail behind those four steps.
- 719 individually addressable requirements. Every clause is a testable MUST or SHOULD with a stable id, generated into a clean specification surface.
- Readiness levels are use gates, not maturity scores. Each level states which AI uses it permits; levels that unlocked no use were removed.
- Rights propagate to derivatives. None of the standards surveyed follow usage rights into embeddings, indexes, caches, and model outputs. This framework does, with an inventory, propagation classes, and verification probes.
- It records what it cannot solve. Prompt injection through retrieved content, non-recallable derivatives, and aggregation across combined context are documented as open residual risks with named limits. One schema example on disk fails validation deliberately, to keep a real gap visible.
- It has been through review. Two full adversarial review passes, an 88-clause acceptance audit, and a five-lens acceptance review, with findings dispositioned on the record.
This repository is a template. Sixteen decisions are left open for each adopter (jurisdiction scope, risk appetite, who funds enforcement, who owns the rights catalogue), each shipped with a recommendation. Closing them is a structured stakeholder survey, not a rewrite:
- Use this template (or clone it). The framework works as-is from day one, following its own recommendations.
- Run the adoption survey:
/init-adoptionwith Claude Code, or work through docs/onboarding/ with your stakeholders by hand. It fills the decision register, names your risk accepters, and sets your parameters. - Tailoring is overlay-only: your answers land in the registers and your adopter profile, while the framework text stays upstream-owned. You keep pulling improvements, and your conformance claims stay comparable with other adopters (ADR 0013).
The recommended first deliverable is not a governed dataset. It is a triage sweep of the AI systems already running against ungoverned data, which reduces real risk within weeks.
| You are | Read this | Time |
|---|---|---|
| Anyone: the whole picture | The handbook: the entire framework, one read | 10 min |
| Executive / CTO | Executive case → the decision pack | 10 min |
| Practitioner, working through it | The nine stage guides: source → describe → contract → govern → serve → consume → audit → security → adopt | 30 min |
| Deciding whether to adopt | Approval pack: what approval commits, what risk it accepts, what it unblocks | 15 min |
| Architect | Handbook → Govern → Serve → Consume → the reference documents | half a day |
| Data producer | Readiness standard → Data contracts | 2 hours |
| Engineer about to build | Build readiness → requirement → capability matrix: which of the 719 bind your component | 15 min |
| Looking up a clause | The specification: all 719 requirements, no prose | as needed |
| Sceptical of all this | Worked example: one messy dataset end to end, including where the framework fails | 1.5 hours |
Full map of every directory, the dependency graph, and the reading order: docs/README.md.
The framework describes five planes. Every capability, control, and document belongs to one of them.
flowchart TB
subgraph GOV["1. Governance plane: declares, never serves"]
G1["Catalogue · contracts · rights profiles<br/>semantics · readiness claims"]
end
subgraph DEC["2. Decision plane"]
D1["Policy decision points<br/>one answer: permit or deny, with a reason"]
end
subgraph ENF["3. Enforcement planes: one enforcement point per access path"]
E1["Query · retrieval · tool · export · ingest…<br/>ten access-plane classes, closed set"]
end
subgraph SUP["4. Context supply chain"]
S1["selection → chunking → indexing<br/>→ retrieval → assembly → delivery"]
end
subgraph EVI["5. Evidence and verification"]
V1["Provenance · audit · quality<br/>lineage · evaluation"]
end
GOV -->|policy inputs| DEC
DEC -->|decisions| ENF
ENF -->|mediates| SUP
SUP -->|answers with provenance| EVI
EVI -->|signals| GOV
classDef g fill:#e8f0fe,stroke:#4a6fa5,color:#1a2b47
classDef d fill:#fdf0e6,stroke:#b5762a,color:#4a2f10
classDef e fill:#fdeaea,stroke:#b04a4a,color:#4a1a1a
classDef s fill:#eaf6ec,stroke:#4a8a5a,color:#14331d
classDef v fill:#f0eafa,stroke:#6a4a9a,color:#261440
class GOV,G1 g
class DEC,D1 d
class ENF,E1 e
class SUP,S1 s
class EVI,V1 v
Figure 1: the five planes. Governance declares and never serves data; decisions are made in one place; every access path crosses an enforcement point; context is assembled through six governed stages; and everything emits evidence. The full reference architecture is in the platform blueprint.
| Framework documents | 24, plus a five-part worked example (by concern) |
| Normative requirements | 719, each individually addressable (index) |
| Prior-art areas classified | 35 as adopted / extended / novel (coverage map) |
| Sources in the register | 231, each with its retrieval status |
| Architecture decisions | 11 ADRs with rejected alternatives (index) |
| Machine-readable schemas | 9, with 13 worked examples (schemas) |
| Adoption tooling | Stakeholder questionnaire + in-repo /init-adoption skill |
| Self-assessment | 2 adversarial review passes + an 88-clause acceptance audit (71 pass / 16 partial / 1 fail, remediated) |
The corpus records its own gaps rather than presenting a finished face.
| Platform capabilities blocked by an unresolved precondition | 9 of 17 (3 more provisional), always current in build readiness |
| Open items | 49 of 64 still open (register) |
| Decisions each adopter takes for itself | 16, shipped open with recommendations (register) |
| Judgements the framework refuses to self-assess | 7 (handover questions) |
Most of the blocking traces to one item: O-20, the machine-readable shapes that eight capabilities bind to and that are still owed (nine have landed; seven remain). This is days of work rather than months.
The reference platform has not been built, by design. The framework is the standard; build decisions belong to each adopter, gated on pilot evidence (see the approval pack).
Directories are numbered in reading order (ADR 0012; gaps absorb inserts, and prefixes are never cited in prose). The five-plane view above is the same material arranged by runtime layer.
docs/
00-handbook/ the whole framework in one read ← start here
10-guides/ nine stage guides, source → adopt
20-framework/ ← the framework itself, vendor-neutral and publishable
10-foundations/ principles, the readiness standard, what fails today
20-semantics/ meaning, grain, knowledge model, discovery
30-contracts/ data contracts and context/tool contracts
40-architecture/ zones, the context supply chain, delivery patterns
50-access/ identity, enforcement, rights, threats
60-assurance/ provenance, evidence, quality, evaluation
70-adoption/ triage, operating model, the worked example
30-platform/ ← the build plan. Deliberately opinionated; names products
40-executive/ the ten-minute read, the roadmap, the approval pack
50-reference/ generated extracts: 719 requirement clauses, indexes, prior-art
60-registers/ glossary · decisions · open items · coverage map
70-schemas/ machine-readable shapes, each with a valid example
80-runbooks/ operational how-tos
onboarding/ the adoption survey and adopter profile
research/ adr/ plans/ audits/ records: fixed paths, filed by date
The framework (20-framework/) and the platform blueprint (30-platform/) are kept separate deliberately. The framework names no product as a required component, so a vendor-neutral version can be published from it directly. The platform blueprint does the opposite: it recommends specific components and gives its reasons. Keeping the boundary at a directory keeps both honest.
Conventions, branch and PR discipline, the adopter overlay contract, and the documentation pipeline are in CLAUDE.md, written for humans and for AI assistants working in a clone.
Navigation artefacts (the requirement index, cross-reference links, backlinks, and the build-readiness table) are generated, not hand-maintained. One command regenerates everything and runs every gate:
python3 tools/docslink.py verifyContributions are welcome: open an issue or PR against the framework itself; adopter-specific tailoring stays in your clone per the overlay model. Historical working records (the original adversarial reviews and planning notes) are preserved in git history at tag internal-archive.