Atlas
kb://architecture/manifest-driven-atlasstable2026-05-21

Manifest-driven atlas — .atlas-deps.yml as single source of truth

architectureatlasmanifestdriftobservability

Every active repo in the org carries a .atlas-deps.yml file. That file is the operator-stated truth about what the repo declares: kind, priority, goals, consumed env vars, exposed endpoints, runtime deps. Atlas treats the manifest as the contract, and diffs it against scraped reality to surface drift.

Why the manifest is the source of truth

Without a manifest, every new agent and human has to learn the topology by grepping Cargo.toml and reading READMEs across 57 active repos. The manifest turns that into a single typed query surface — both for atlas's own dashboards and for any agent reading the MCP endpoint.

100% of active repos carry a .atlas-deps.yml as of 2026-05-21. The five deprecated/archived repos and the main openalice repo are exempt by spec (charter governance: kind=deprecated repos are read-only).

What the manifest propagates to

A single edit to .atlas-deps.yml fans out to:

  • `/graph` — node kind, priority ring, runtime edges
  • `/repos/[name]` — manifest panel, env drift panel, runtime deps, goals roadmap
  • Prometheus `file_sd_configs` — exposed endpoints become scrape targets (see kb://architecture/slo-auto-targets-pipeline)
  • `wiki.md` per repo — paste-able markdown summary
  • MCP — atlas.repo.manifest returns the same blob

Drift detection

Atlas runs two drift checks each scan:

  1. Env drift — what consumes_env: declares vs what the source code actually reads. Surfaces declared-unused + undeclared-but-used.
  2. Quality drift — manifest goals + feature annotations + readme coverage rolled into a quality_breakdown.drift 0-100 score.

The 2026-05-21 polish-todo board surfaced openalice-atlas itself with the worst declared-vs-actual env drift after openalice-lab (drift 10, 9 env-drift entries). The auditor needed its own audit — that finding only existed because the manifest contract was already enforced.

Why this matters for agents

When an agent needs «what env vars does service X consume», the answer is one HTTP call away — not a recursive grep. Atlas's MCP exposes seven read-only tools that all sit on top of the parsed manifest: atlas.repo.manifest, atlas.repo.runtime_deps, atlas.repo.health, atlas.search, and three more.

How to extend the spec

docs/manifest-spec.md is the contract. Changes must:

  1. Be backward-compatible (existing manifests keep parsing)
  2. Update the parser in ingestor/src/manifest.rs
  3. Update the validator (atlas-ingestor validate <path>)
  4. Add a migration if a new DB column is required
  5. Pre-coordinate with any other agent / repo that writes manifests