config-atlas/workplans/ATLAS-WP-0002-registry-foundation.md

---
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.<domain>.<system>.<name>`), `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
```
</content>