From e7dd84890d675843d165a4468e2b4d679c5aad87 Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 26 Jun 2026 22:40:48 +0200 Subject: [PATCH] chore(workplans): restructure and extend ATLAS-WP-0002; archive WP-0001 Realign ATLAS-WP-0002 to ArchitectureBlueprint Phase 0-1 and the PRD MVP: add context/exit-condition/sequencing, refine the three existing tasks with acceptance criteria, and extend with three new tasks (T04 canon mapping, T05 surface.* namespace + reuse-surface federation, T06 CI validation). Existing task ids and state_hub_task_ids preserved. Archive finished ATLAS-WP-0001 to workplans/archived/ with date prefix per the workplan convention. Co-Authored-By: Claude Opus 4.8 --- .../ATLAS-WP-0002-registry-foundation.md | 128 +++++++++++++++--- ...60626-ATLAS-WP-0001-statehub-bootstrap.md} | 0 2 files changed, 112 insertions(+), 16 deletions(-) rename workplans/{ATLAS-WP-0001-statehub-bootstrap.md => archived/260626-ATLAS-WP-0001-statehub-bootstrap.md} (100%) diff --git a/workplans/ATLAS-WP-0002-registry-foundation.md b/workplans/ATLAS-WP-0002-registry-foundation.md index df9265c..fc09481 100644 --- a/workplans/ATLAS-WP-0002-registry-foundation.md +++ b/workplans/ATLAS-WP-0002-registry-foundation.md @@ -14,10 +14,48 @@ state_hub_workstream_id: "27b42720-1bd7-4755-ab2f-59a6d095a2c3" # Configuration atlas registry foundation -Replace inherited `repo-seed` template artifacts with config-atlas-specific -registry scaffold and establish the configuration surface model. +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. -## Define configuration surface schema +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: todo +priority: high +``` + +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 @@ -26,10 +64,19 @@ priority: high state_hub_task_id: "125a4ad3-ddd4-4aee-bb94-9433a5fa4651" ``` -Document the configuration surface model: required fields (id, name, owner, -source path, scope, validation), naming conventions, and index file layout. -Add schema docs under `registry/` (e.g. `registry/README.md` expansion and a -`docs/configuration-surface-schema.md` reference). +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 @@ -40,13 +87,18 @@ priority: high state_hub_task_id: "2d8e41e9-ba93-4a1a-862b-993da03df1f9" ``` -Remove `capability.infotech.repo-template` and other repo-seed artifacts from +Remove `capability.infotech.repo-template` and other `repo-seed` artifacts from `registry/`. Add the config-atlas capability entry and update -`registry/indexes/capabilities.yaml`. Remove or relocate inherited template +`registry/indexes/capabilities.yaml`. Relocate or delete inherited template consumer docs (`docs/template-validation-checklist.md`, -`docs/statehub-register.md`) — those belong in `repo-seed`. +`docs/statehub-register.md`) — those belong to `repo-seed`, not here. Update any +references (e.g. `registry/README.md` points at reuse-surface templates). -## Seed initial configuration surfaces +- **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 @@ -55,12 +107,56 @@ priority: medium state_hub_task_id: "9b8bb1c2-a6ee-4b6e-91a4-2cd902fb52ff" ``` -Index 3–5 high-value configuration surfaces already present in the ecosystem -(e.g. State Hub API config, warden routing catalog, reuse-surface registry -layout). Each entry must link to canonical source files, not duplicate values. +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). -After workplan file updates, run from `~/state-hub`: +- **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: todo +priority: medium +``` + +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: todo +priority: medium +``` + +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 -``` \ No newline at end of file +``` + diff --git a/workplans/ATLAS-WP-0001-statehub-bootstrap.md b/workplans/archived/260626-ATLAS-WP-0001-statehub-bootstrap.md similarity index 100% rename from workplans/ATLAS-WP-0001-statehub-bootstrap.md rename to workplans/archived/260626-ATLAS-WP-0001-statehub-bootstrap.md