diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md index 6db0d62..fdbefee 100644 --- a/.claude/rules/repo-boundary.md +++ b/.claude/rules/repo-boundary.md @@ -1,11 +1,21 @@ ## Repo boundary -This repo owns **config-atlas** only — the federated configuration surface -registry and its documentation. It does not own: +This repo owns the **read-only, cross-kind configuration map and evidence layer** — +the federated configuration surface registry and its documentation. Its novel core +is the cross-kind surface classification, the layering order, and effective-config +*path* rendering. Everything else is referenced, not owned. +It does **not** own (sister repo → relationship): + +- Configuration *vocabulary* / concepts (`info-tech-canon`) — **map, don't redefine** +- Repository *scanning / candidate / approval* machinery (`repo-scoping`) — **reuse** +- *Domain placement & ownership identity* (`domain-tree`) — **reference** +- The *registry schema & federation hub* (`reuse-surface`) — **federate under it** +- *Runtime resolution & control* of feature availability, incl. resolver and kill + switches (`feature-control`) — **link, never re-derive** - Repo template bootstrap (`repo-seed`) -- Capability reuse registry (`reuse-surface`) -- Secret storage or live config values (`railiance-platform` / OpenBao) -- Feature flag control plane (`feature-control`) -- State Hub implementation (`state-hub`) -- Deployment and infrastructure execution (`railiance-infra`, `ops-bridge`) \ No newline at end of file +- Secret *values* / live config (`railiance-platform` / OpenBao) — reference only +- State Hub graph/identity store (`state-hub`) — contribute config-typed edges +- Deployment and infrastructure execution (`railiance-infra`, `ops-bridge`) + +See `docs/ecosystem-boundaries.md` for the full boundary-and-reuse analysis. \ No newline at end of file diff --git a/docs/ecosystem-boundaries.md b/docs/ecosystem-boundaries.md new file mode 100644 index 0000000..451e4f1 --- /dev/null +++ b/docs/ecosystem-boundaries.md @@ -0,0 +1,140 @@ +# Ecosystem Boundaries & Reuse — config-atlas among its sister repos + +> How config-atlas should tighten its responsibility boundaries and reuse existing +> concepts/functionality from five sister repos rather than reinventing them. +> Drafted 2026-06-26. Companion to [`INTENT.md`](../INTENT.md), +> [`SCOPE.md`](../SCOPE.md), [`ArchitectureBlueprint.md`](../ArchitectureBlueprint.md), +> and [`.claude/rules/repo-boundary.md`](../.claude/rules/repo-boundary.md). + +--- + +## 1. The one-sentence boundary for each repo + +| Repo | Owns | config-atlas relationship | +|------|------|---------------------------| +| **info-tech-canon** | The shared *vocabulary*: canonical concepts, models (Governance, Data, DevSecOps, Landscape, Access), mappings, patterns. Markdown-first semantic operating layer. | **Consume, don't redefine.** Map config-atlas terms (surface, scope/layer, kind, mutability, effective config, evidence) to ITC concepts. | +| **repo-scoping** | Turning repos into source-linked maps via deterministic scanners + optional LLM candidates + human approval. Hierarchy `Scope→Ability→Capability→Feature→Evidence→Fact`. | **Reuse the machinery.** config-atlas "connectors" are repo-scoping's scanner→candidate→approval pipeline, specialized to config surfaces. | +| **domain-tree** | Organizational backbone: primary domain placement + secondary bindings for repos, services, users, datasets, policies. Identity-stable domains. | **Reference for ownership/placement.** A surface's `owner`/domain should resolve to domain-tree bindings. | +| **reuse-surface** | The capability registry model, entry schema, validation CLI, and federation hub. Maturity vectors (D/A/C/R). | **Federate under it.** config-atlas is a federated registry peer; its surface entry is a typed sibling of the capability entry. (Already reused.) | +| **feature-control** | The *runtime* feature-availability **control plane**: OpenFeature integration, multi-scope decisions, resolver, kill switches, audit. | **Hard delegation boundary.** config-atlas maps feature flags as *one config kind* and links to feature-control as the authority; it never resolves or controls them. | + +The clean north: **config-atlas is read-first cartography across all config kinds; +each adjacent repo owns one authoritative slice that config-atlas points at.** + +--- + +## 2. Overlap hotspots and how to resolve them + +These are the places where config-atlas, as currently written, risks redefining or +rebuilding something a sister repo already owns. + +### 2.1 "Control plane" + scope model + resolver + kill switches — vs feature-control +**The sharpest overlap.** Both repos use *control plane* language, both define a +*scope model*, both talk about *effective decision / resolver* and *kill switches*. +feature-control already enumerates scopes (platform, installation, environment, +deployment, vendor, tenant, domain, organization, group, user, service, repository, +agent) and its own out-of-scope explicitly forbids "becoming a generic +configuration database for unrelated application settings" — which is exactly +config-atlas's job. The boundary is therefore mutually reinforcing if stated +crisply: + +- **feature-control** = runtime control plane for *one kind* (feature availability), + write/runtime, OpenFeature-native, owns the feature *resolver*. +- **config-atlas** = read-only map/evidence atlas across *all kinds*, references + feature-control's flags and resolver rather than re-deriving them. + +**Action:** config-atlas must not ship a runtime resolver (already deferred in the +blueprint — restate it as a hard boundary against feature-control specifically). +The `feature-flag` `kind` entries should carry a `sources[]` link to the +feature-control key, not duplicate its rules. Drop independent "kill switch" +language from config-atlas — that is feature-control's `Kill Switch` concept. + +### 2.2 The scope/layer taxonomy — vs feature-control + InfoTechCanon +config-atlas defines `L0–L9` layers; feature-control defines its scope list; +InfoTechCanon owns Governance/Landscape/Org concepts underneath both. Three +independent scope vocabularies is exactly the "integration by interpretation" that +InfoTechCanon exists to prevent. + +**Action:** Adopt **one shared scope vocabulary** grounded in InfoTechCanon and +already qualified by feature-control's `EvaluationScope`. Express config-atlas's +`L0–L9` as an *ordering over* that shared vocabulary, not a new set of names. + +### 2.3 Concept ownership — vs InfoTechCanon +config-atlas's research/blueprint introduce `kind`, `mutability class`, `merge +semantics`, `security_class`, `effective configuration`, `evidence`. Several of +these already have ITC homes (Governance: policy/decision/evidence; DevSecOps: +delivery/mutability; Data: schema/contract/classification). + +**Action:** Add `docs/canon-mapping.md` mirroring feature-control's pattern — +entity/relationship tables stating which terms config-atlas **consumes** from ITC +(ITC-GOV, ITC-DATA, ITC-DEVSECOPS, ITC-LAND) vs **owns** (the configuration-surface +entry, layering order, the cross-kind map itself). Propose any genuinely new terms +(e.g. "configuration surface", "effective-config path") to ITC as extensions. + +### 2.4 Discovery connectors — vs repo-scoping +The blueprint's §4 connectors (read-only scanners emitting candidate entries for +PR review) reproduce repo-scoping's deterministic-scanner + candidate-graph + +approve→registry-truth workflow and its source-linked evidence hierarchy. + +**Action:** Reuse, don't rebuild. Two viable shapes: +- **(a) Consume repo-scoping facts** — config-atlas reads repo-scoping's observed + facts/evidence as connector input, adding only the config-surface classification. +- **(b) Extend repo-scoping** with config-surface scanners, and have config-atlas + curate/federate the results. +Either way, the candidate→approval→truth state machine and the `Evidence→Fact` +provenance model come from repo-scoping. config-atlas adds the *config-kind + +layer* semantics on top. + +### 2.5 Ownership & relationships — vs domain-tree + State Hub +config-atlas entries carry `owner` and cross-repo relations (`consumed_by`, +`depends_on_secret`). domain-tree owns primary/secondary resource→domain bindings; +the State Hub owns workstream/relationship records. + +**Action:** `owner`/placement should resolve to domain-tree bindings (reference an +identity, don't restate org structure). Config-typed *edges* go to the State Hub +graph (already the blueprint's §5 decision). config-atlas stores the config +semantics of the edge; domain-tree/State Hub store identity and topology. + +### 2.6 Registry entry schema & federation — vs reuse-surface +Already reused (the surface-entry schema is modeled on the capability entry, and +validation runs through `reuse-surface validate`). The open question is whether a +*configuration surface* is its own federated entry type or a capability `kind`. + +**Action:** Treat the configuration-surface entry as a **typed sibling** under +reuse-surface's federation (its own schema, federated by the same hub), not a new +federation mechanism. Confirm the entry `id` namespace (`surface.*`) is reserved in +the reuse-surface federation roster so the two registries don't collide. + +--- + +## 3. Tightened boundary statement (proposed for repo-boundary.md) + +> config-atlas owns the **read-only, cross-kind configuration map and evidence +> layer**. It does **not** own: +> - the configuration *vocabulary* (→ **info-tech-canon**; map, don't redefine); +> - repository *scanning / candidate / approval* machinery (→ **repo-scoping**; reuse); +> - *domain placement and ownership identity* (→ **domain-tree**; reference); +> - the *registry schema & federation hub* (→ **reuse-surface**; federate under it); +> - the *runtime resolution & control* of feature availability, incl. resolver and +> kill switches (→ **feature-control**; link, never re-derive); +> - secret *values* (→ OpenBao; reference only); +> - the State Hub *graph/identity* store (→ State Hub; contribute config-typed edges). + +--- + +## 4. Concrete reuse actions (maps onto the blueprint roadmap) + +| Action | Reuses | Blueprint phase | +|--------|--------|-----------------| +| Add `docs/canon-mapping.md` (consumed vs owned terms) | info-tech-canon | Phase 0 (Canon) | +| Express `L0–L9` as an ordering over the shared ITC/feature-control scope vocab | info-tech-canon, feature-control | Phase 0 | +| Reserve `surface.*` id namespace + validate via reuse-surface | reuse-surface | Phase 0–1 | +| Source connectors from repo-scoping facts (option a) instead of bespoke scanners | repo-scoping | Phase 2 | +| Resolve `owner` to domain-tree bindings; push config edges to State Hub | domain-tree, State Hub | Phase 2–3 | +| `feature-flag` entries link to feature-control keys; no local resolver/kill-switch | feature-control | Phase 3 | + +Net effect: config-atlas keeps only its genuinely novel core — the **cross-kind +configuration-surface classification, the layering order, and the effective-config +*path* rendering** — and borrows vocabulary, scanning, ownership, schema/federation, +and runtime control from the four repos that already own them. + diff --git a/ArchitectureBlueprint.md b/specs/ArchitectureBlueprint.md similarity index 100% rename from ArchitectureBlueprint.md rename to specs/ArchitectureBlueprint.md