--- id: ATLAS-WP-0002 type: workplan title: "Configuration atlas registry foundation" domain: infotech repo: config-atlas status: finished owner: codex topic_slug: custodian created: "2026-06-26" updated: "2026-06-26" state_hub_workstream_id: "27b42720-1bd7-4755-ab2f-59a6d095a2c3" --- # Configuration atlas registry foundation Establish config-atlas's **Canon and registry foundation** — the surface-entry schema, the canon mapping, the replacement of inherited `repo-seed` artifacts, the first seeded surfaces, federation, and CI validation. This realizes **Phase 0 (Canon) + Phase 1 (seed)** of [`specs/ArchitectureBlueprint.md`](../specs/ArchitectureBlueprint.md) §6 and the **MVP** of [`specs/ProductRequirementsDocument.md`](../specs/ProductRequirementsDocument.md) §11. It owns only the *map and evidence* layers — no resolver, no delivery, no control (see [`SCOPE.md`](../SCOPE.md) and [`.claude/rules/repo-boundary.md`](../.claude/rules/repo-boundary.md)). **Exit condition:** a real `surface.*` entry validates in CI; inherited template artifacts are gone; `docs/canon-mapping.md` exists; the `surface.*` namespace is reserved under reuse-surface federation. **Sequencing:** T04 (canon mapping) and T01 (schema) come first; T02 (cleanup) is independent; T03 (seed) and T06 (CI) depend on T01; T05 (federation) depends on the `surface.*` id scheme defined in T01. Later phases (connectors, explain & graph — blueprint Phases 2–3) will be separate workplans, not tasks here. ## Author canon mapping (consume, don't redefine) ```task id: ATLAS-WP-0002-T04 status: done priority: high state_hub_task_id: "e96f00bc-d858-4cfa-be6c-10de8de7b529" ``` Result 2026-06-26: Authored `docs/canon-mapping.md` mirroring feature-control's pattern, using real ITC ids (itc-gov/data/devsecops/land/org/access/sec/tag). Entity + relationship mapping (consume/reference/align/own), read-model surface, gaps, validation hooks, extension candidates, and ITC artifact references. Resolves the `(planned)` links in PRD §5 and ecosystem-boundaries §2.3. Create `docs/canon-mapping.md` mapping config-atlas terms to InfoTechCanon and sibling repos: **consume** ITC-GOV (policy/decision/evidence), ITC-DATA (schema/contract/classification), ITC-DEVSECOPS (delivery/mutability), ITC-LAND (env/deployment); **reference** ITC-ORG ownership via `domain-tree`; **align** the scope vocabulary with feature-control `EvaluationScope`; **own** the configuration surface, the L0–L9 layering order, and the cross-kind map. Mirror the pattern of `~/feature-control/docs/canon-mapping.md`. Resolves the dangling `(planned)` references in PRD §5 and `docs/ecosystem-boundaries.md` §2.3. - **Acceptance:** `docs/canon-mapping.md` exists with an entity table marking each term consumed / referenced / aligned / owned; PRD §5 and ecosystem-boundaries §2.3 links resolve. ## Define configuration-surface schema ```task id: ATLAS-WP-0002-T01 status: done priority: high state_hub_task_id: "125a4ad3-ddd4-4aee-bb94-9433a5fa4651" ``` Result 2026-06-26: Added `schemas/surface-entry.schema.json` (JSON Schema Draft 2020-12; `additionalProperties:false` throughout to forbid inline values), `docs/configuration-surface-schema.md` (fields, kind taxonomy, L0–L9 ordering, explicit merge rules), and a validating seed entry `registry/surfaces/surface.infotech.state-hub.api-config.md`. Expanded `registry/README.md`. Verified: schema is valid Draft 2020-12, the example entry validates, and a forbidden inline `value` field is correctly rejected. CUE deferred (PRD open question 4). Author the machine-checkable surface-entry schema and the layering/merge model. Add `schemas/surface-entry.schema.json` (JSON Schema; evaluate CUE per PRD open question 4) matching the entry shape in ArchitectureBlueprint §3 / PRD §10: `id` (`surface...`), `kind` (closed taxonomy), `scope` (`allowed_layers` over L0–L9, `default_layer`), `mutability`, `security_class`, `schema` (contract, **no values**), `sources[]` (with layer `role`), `relations`, `evidence`. Expand `registry/README.md` and add `docs/configuration-surface-schema.md` documenting the L0–L9 order and explicit merge rules. - **Acceptance:** one real example `surface.*` entry validates against the schema; schema forbids literal values and secret values; layer names match the shared scope vocabulary (no new scope names). ## Replace inherited template registry ```task id: ATLAS-WP-0002-T02 status: done priority: high state_hub_task_id: "2d8e41e9-ba93-4a1a-862b-993da03df1f9" ``` Result 2026-06-26: Removed `capability.infotech.repo-template` and the inherited template consumer docs (`docs/statehub-register.md`, `docs/template-validation-checklist.md`). Added `capability.infotech.config-surface-atlas` and rewrote `registry/indexes/capabilities.yaml` to list only config-atlas-owned entries. Remove `capability.infotech.repo-template` and other `repo-seed` artifacts from `registry/`. Add the config-atlas capability entry and update `registry/indexes/capabilities.yaml`. Relocate or delete inherited template consumer docs (`docs/template-validation-checklist.md`, `docs/statehub-register.md`) — those belong to `repo-seed`, not here. Update any references (e.g. `registry/README.md` points at reuse-surface templates). - **Acceptance:** no `repo-template`/`statehub-register`/`template-validation` artifacts remain; `capabilities.yaml` lists only config-atlas-owned entries; `reuse-surface validate --root .` passes. ## Establish registry layout and seed initial surfaces ```task id: ATLAS-WP-0002-T03 status: done priority: medium state_hub_task_id: "9b8bb1c2-a6ee-4b6e-91a4-2cd902fb52ff" ``` Result 2026-06-26: Created `registry/indexes/surfaces.yaml` and seeded 4 surfaces: state-hub api-config (app-config), ops-warden routing-catalog (policy), reuse-surface federation-sources (app-config), ops-bridge tunnel-config (infra-state). All source-linked, no values; secret deps recorded as references (`depends_on_secret`). All validate via the T06 gate. Create `registry/surfaces/` and `registry/indexes/surfaces.yaml`. Hand-author 3–5 high-value configuration surfaces already present in the ecosystem (e.g. State Hub API config, warden routing catalog, reuse-surface registry layout) with `surface.*` ids, classified by `kind` and `scope`, **source-linked, never duplicating values**. This is the start of the Phase 1 seed (target 10–20). - **Acceptance:** ≥3 `surface.*` entries exist and validate; each links to canonical source files; an `owner` is set on each and resolves to a domain-tree identity (or is flagged unknown); no entry contains a literal or secret value. ## Reserve `surface.*` namespace and federate under reuse-surface ```task id: ATLAS-WP-0002-T05 status: done priority: medium state_hub_task_id: "2a27434b-4eed-419a-b903-07cff9027bd6" ``` Result 2026-06-26: Registered config-atlas in reuse-surface (`registry/federation/sources.yaml` + `local-repo-roster.yaml`) and reserved the `surface.*` namespace via a new "Id namespace ownership" section in `docs/RegistryFederation.md` (surface.* is a typed sibling of capability.*, not federated). `federation compose` succeeds (config-atlas capability now in `federated.yaml`). Committed in reuse-surface as 08f3bb5. Raw URL returns 303 (required:false) — fetchability awaits the same publish fix tracked for state-hub/feature-control; not a config-atlas-side blocker. Reserve the `surface.*` id namespace in the reuse-surface federation roster so the configuration-surface registry interoperates with the capability surface without collision (PRD FR-10; ecosystem-boundaries §2.6). Treat the surface entry as a **typed sibling** of the capability entry, federated by the same hub — not a new federation mechanism. Coordinate via reuse-surface federation docs (`~/reuse-surface/docs/RegistryFederation.md`). - **Acceptance:** `surface.*` is reserved in the federation roster; config-atlas surface entries are discoverable via reuse-surface federation; no id collision with capability entries. ## Wire CI validation ```task id: ATLAS-WP-0002-T06 status: done priority: medium state_hub_task_id: "da6e44a7-ed87-433e-b183-f926e7e0caf8" ``` Result 2026-06-26: Added `tools/validate_registry.py` (schema + index-consistency gate; forbids inline values via additionalProperties:false), a `Makefile` (`make validate` = schema + whitespace + reuse-surface), and `.github/workflows/validate.yml` (runs on GitHub & Gitea Actions). Documented in `.claude/rules/stack-and-commands.md`. Verified: 4 seed surfaces pass; a malformed entry (bad kind, inline `value`, unindexed) is rejected with rc=1. Wire registry validation to run on every change: `reuse-surface validate --root .`, surface-entry schema validation (T01), and `git diff --check` (PRD FR-9, NFR-6). Document the check in `AGENTS.md` / `.claude/rules/stack-and-commands.md` so agents and CI run the same gate. - **Acceptance:** a malformed entry blocks the check; a well-formed seed entry passes; the command sequence is documented for both agents and CI. --- After workplan or registry file updates, sync from `~/state-hub`: ```bash make fix-consistency REPO=config-atlas ```