From 1866505ba429f56baa7b4c5ee14cd8671755152c Mon Sep 17 00:00:00 2001 From: tegwick Date: Fri, 26 Jun 2026 23:57:59 +0200 Subject: [PATCH] plan(workplans): add ATLAS-WP-0003 (connectors) and ATLAS-WP-0004 (explain & graph) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 2 (ATLAS-WP-0003): read-only discovery connectors reusing repo-scoping's scanner/candidate/approval pipeline — connector contract, repo-scoping fact ingestion, git-config scanner, feature-control flag connector, stale/unowned detection. Phase 3 (ATLAS-WP-0004): effective-config explain + knowledge graph — static override-path resolver, config explain tool, config-typed edges to the State Hub graph, blast-radius view, determinism tests. File-first per ADR-001; state_hub ids to be written by fix-consistency. Co-Authored-By: Claude Opus 4.8 --- .../ATLAS-WP-0003-discovery-connectors.md | 129 +++++++++++++++++ workplans/ATLAS-WP-0004-explain-and-graph.md | 130 ++++++++++++++++++ 2 files changed, 259 insertions(+) create mode 100644 workplans/ATLAS-WP-0003-discovery-connectors.md create mode 100644 workplans/ATLAS-WP-0004-explain-and-graph.md diff --git a/workplans/ATLAS-WP-0003-discovery-connectors.md b/workplans/ATLAS-WP-0003-discovery-connectors.md new file mode 100644 index 0000000..ee8a178 --- /dev/null +++ b/workplans/ATLAS-WP-0003-discovery-connectors.md @@ -0,0 +1,129 @@ +--- +id: ATLAS-WP-0003 +type: workplan +title: "Discovery connectors" +domain: infotech +repo: config-atlas +status: ready +owner: codex +topic_slug: custodian +created: "2026-06-26" +updated: "2026-06-26" +--- + +# Discovery connectors + +Grow the configuration-surface registry from **automated discovery** instead of +only hand authoring — by reusing `repo-scoping`'s scanner → candidate → approval +machinery rather than building bespoke scanners. + +This is **Phase 2** of [`specs/ArchitectureBlueprint.md`](../specs/ArchitectureBlueprint.md) +§6 and realizes PRD FR-8 ([`specs/ProductRequirementsDocument.md`](../specs/ProductRequirementsDocument.md)). +Connectors are **read-only and stateless**: they emit *candidate* surface entries +for human/agent PR review and never write any source system or auto-merge +([`docs/ecosystem-boundaries.md`](../docs/ecosystem-boundaries.md) §2.4). + +**Depends on:** ATLAS-WP-0002 (surface schema, registry layout, CI gate). The +candidate → approval → registry-truth state machine and source-linked evidence +model are reused from `repo-scoping`, not reinvented. + +**Exit condition:** at least one connector produces candidate surfaces that enter +via PR, validate against the schema, and can be promoted to entries; stale/unowned +surfaces are reported. No connector mutates a source system. + +**Sequencing:** T01 (contract) first; T02–T04 (connectors) depend on T01 and may +proceed in parallel; T05 (stale/unowned) depends on having connector-produced data. + +## Define the connector contract and candidate workflow + +```task +id: ATLAS-WP-0003-T01 +status: todo +priority: high +``` + +Specify the read-only connector contract and the candidate lifecycle. Define the +candidate entry format (a surface entry with `status: candidate` + provenance) and +its location (`registry/surfaces/candidates/`), and the `connector → candidate YAML +→ PR → validate → promote/merge` flow. Reuse `repo-scoping`'s +`Scope→…→Evidence→Fact` provenance and candidate→approval model +(`~/repo-scoping/docs/scope-md-spec.md`, `src/repo_scoping/candidate_graph/`). +Document in `docs/discovery-connectors.md`. + +- **Acceptance:** a documented contract (inputs, candidate output shape, promotion + rules); connectors are specified as stateless and non-mutating; the candidate + schema reuses the surface-entry schema with a `candidate` status + provenance. + +## repo-scoping fact ingestion connector + +```task +id: ATLAS-WP-0003-T02 +status: todo +priority: high +``` + +Build the connector that consumes `repo-scoping` observed facts/evidence as input +and emits candidate configuration surfaces, adding only the config-kind and layer +classification on top (ecosystem-boundaries §2.4 option a). Map repo-scoping facts +about config files/env/params to `surface.*` candidates with `kind`, `scope`, and +`sources[]` populated. + +- **Acceptance:** running the connector against a registered repo's repo-scoping + facts emits valid candidate surfaces (schema-valid) with source links; zero writes + to repo-scoping or the scanned repo. + +## git-config deterministic scanner + +```task +id: ATLAS-WP-0003-T03 +status: todo +priority: medium +``` + +Build a deterministic scanner over repository config surfaces — env files, YAML/TOML +config, Kubernetes ConfigMap/Secret *references*, and Helm `values*.yaml` overlays — +emitting candidate entries with inferred `kind` and layer `role` per source. Secret +references become `secret-ref` candidates (reference only, never values). + +- **Acceptance:** scanning a sample repo emits candidates classified by kind, with + Helm overlays mapped to layer roles; secret references carry no values. + +## feature-control flag connector + +```task +id: ATLAS-WP-0003-T04 +status: todo +priority: medium +``` + +Build a connector that inventories `feature-control` keys and emits `feature-flag` +surfaces that **link** to the feature-control key (`sources[].role: +feature-control-key`) and contain no evaluation logic (PRD FR-12; reinforces the +delegation boundary). Surface stale flags as a signal. + +- **Acceptance:** feature-control keys appear as `feature-flag` candidate surfaces + linking to the authoritative key; config-atlas holds no flag-evaluation logic. + +## Stale and unowned surface detection + +```task +id: ATLAS-WP-0003-T05 +status: todo +priority: medium +``` + +Add a report that flags surfaces with no resolvable `owner` (against domain-tree) +and surfaces whose sources were not seen in the latest scan (stale/drift signal), +using `evidence.last_seen`. Wire it into the validation tooling (`tools/`). + +- **Acceptance:** the report lists unowned and stale surfaces; an unowned or + unseen-since-N-days surface is surfaced for review. + +--- + +After workplan or registry file updates, sync from `~/state-hub`: + +```bash +make fix-consistency REPO=config-atlas +``` + diff --git a/workplans/ATLAS-WP-0004-explain-and-graph.md b/workplans/ATLAS-WP-0004-explain-and-graph.md new file mode 100644 index 0000000..b71d916 --- /dev/null +++ b/workplans/ATLAS-WP-0004-explain-and-graph.md @@ -0,0 +1,130 @@ +--- +id: ATLAS-WP-0004 +type: workplan +title: "Effective-config explain and graph" +domain: infotech +repo: config-atlas +status: ready +owner: codex +topic_slug: custodian +created: "2026-06-26" +updated: "2026-06-26" +--- + +# Effective-config explain and graph + +Turn the registry into the **read-first control-plane MVP**: given a key, show its +layer path, what overrides what, its owner, its consumers, and its blast radius — +**statically, from source links, without reading any live value**. + +This is **Phase 3** of [`specs/ArchitectureBlueprint.md`](../specs/ArchitectureBlueprint.md) +§6 and realizes PRD FR-5 and FR-7 +([`specs/ProductRequirementsDocument.md`](../specs/ProductRequirementsDocument.md)). +The configuration knowledge graph reuses the **State Hub** relationship store rather +than building a new graph database ([`docs/ecosystem-boundaries.md`](../docs/ecosystem-boundaries.md) +§2.5; [`research/configuration-control-plane.md`](../research/configuration-control-plane.md) §5). + +**Depends on:** ATLAS-WP-0002 (entries carry `sources[].role` and `relations`). +Benefits from, but does not require, ATLAS-WP-0003 (connectors enrich coverage). + +**Hard boundary:** this renders the effective-config *path* only. Resolving the +actual effective *value* is out of scope (delegated downstream); `feature-flag` +surfaces link to feature-control and are never re-resolved here. + +**Exit condition:** `config explain ` emits an ordered override path +with winning layer, what it overrode, validating schema, and owner; config-typed +edges are expressible to the State Hub graph; a blast-radius view lists affected +consumers. + +**Sequencing:** T01 (resolver) → T02 (CLI) and T05 (tests); T03 (graph edges) → +T04 (blast-radius). T01 and T03 may start in parallel. + +## Effective-config path resolver (static) + +```task +id: ATLAS-WP-0004-T01 +status: todo +priority: high +``` + +Implement a static resolver that, from a surface's `sources[]` (with layer `role`), +the L0–L9 ordering, and the explicit merge rules, produces the **override path**: +ordered contributing layers, the winning layer, what each overrode, the validating +schema, and the owner — never a live value. Honors non-overridable guardrails. See +the `config explain` shape in [`wiki/ConfigLayering.md`](../wiki/ConfigLayering.md). + +- **Acceptance:** given a surface with ordered sources, the resolver returns a + deterministic, order-independent override path with owner + validator refs and no + resolved value. + +## `config explain` tool + +```task +id: ATLAS-WP-0004-T02 +status: todo +priority: high +``` + +Add a `tools/` command (e.g. `config_explain.py`) that takes a `surface.*` id and +renders the resolver output as the human/agent-readable `config explain` view. +Reuse the existing `tools/` + Makefile pattern (`make explain SURFACE=...`). + +- **Acceptance:** `config explain surface.infotech.state-hub.api-config` prints the + ordered layer path, overrides, validator, owner, and consumers. + +## Config knowledge graph edges to State Hub + +```task +id: ATLAS-WP-0004-T03 +status: todo +priority: medium +``` + +Emit config-typed edges (`consumed_by`, `overrides`, `depends_on_secret`, +`related_to`) from surface entries to the **State Hub** relationship/graph model, +contributing the config semantics of each edge while the hub stores topology +(PRD FR-7; ecosystem-boundaries §2.5). Do not build a separate graph store. + +- **Acceptance:** declared edges from the seed surfaces are expressed to the State + Hub without duplicating its store; edges are queryable by surface id. + +## Blast-radius / dependency view + +```task +id: ATLAS-WP-0004-T04 +status: todo +priority: medium +``` + +Build a view that, for a given surface, traverses the graph to list affected +consumers, dependent surfaces, and referenced secrets — the +`config key → service → tenant → feature → secret → owner` chain from +research §5. Supports change-risk reasoning before a change. + +- **Acceptance:** for a surface, the view lists downstream consumers and dependent + surfaces; a change to a high-fan-out surface is visibly higher risk. + +## Resolver determinism tests + +```task +id: ATLAS-WP-0004-T05 +status: todo +priority: medium +``` + +Add tests proving the override path is deterministic and order-independent +(consistent with the merge-rule and CUE-unification rationale, +research §3.3), and that no live or secret value ever appears in explain output. +Wire into the CI gate (`make validate`). + +- **Acceptance:** tests pass in CI; an explain output containing a literal value or + secret fails the test. + +--- + +After workplan or registry file updates, sync from `~/state-hub`: + +```bash +make fix-consistency REPO=config-atlas +``` +