plan(workplans): add ATLAS-WP-0003 (connectors) and ATLAS-WP-0004 (explain & graph)

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 <noreply@anthropic.com>

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
+```
+</content>

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 <surface-id>` 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
+```
+</content>