config-atlas/docs/ecosystem-boundaries.md

# 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`](../specs/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.
</content>