generated from coulomb/repo-seed
tegwick
b03b75efd4
Some checks failed
validate-registry / validate (push) Has been cancelled
Register config-atlas in reuse-surface federation and reserve the surface.* namespace (reuse-surface commit 08f3bb5). Mark T05 done and WP-0002 finished (6/6 tasks complete). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
209 lines
9.0 KiB
Markdown
209 lines
9.0 KiB
Markdown
---
|
||
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>
|