# Configuration Domain

**Status:** Approved target-state baseline  
**First realization:** I0.

## Target State

Configuration is a first-class typed registry with scope, inheritance, provenance, validation and mutation consequences.

```text
ConfigurationDefinition
   ↓ values/overrides
System -> Project -> Plan -> Task -> Run
   ↓
EffectiveConfiguration(value + provenance chain)
```

## Core Primitives

`ConfigurationDefinition` defines key, schema/type, default, allowed scopes, merge/override strategy, sensitivity/reference rules, mutability, constraints, description, effect category and compatibility/versioning.

`ConfigurationValue` stores an override/reference at one scope with revision and Principal/audit.

`EffectiveConfiguration` is resolved output with full provenance, not a separately edited value.

## Invariants From Day 1

- every configurable product behavior has a typed definition;
- unknown/invalid keys fail validation rather than silently applying;
- secrets use CredentialReference, never raw config values;
- locked/immutable values remain visible with explanation;
- reset removes override and reveals inherited value;
- lower scopes never broaden security ceilings;
- changes that alter execution semantics can invalidate readiness/evidence and require new Run/PlanRevision;
- configuration schema/version changes have migration/default behavior.

## Effect Categories

Examples:

```text
presentation-only
future-runs-only
requires replan/re-readiness
requires service reload/restart
security-sensitive / Approval required
immutable after resource creation
```

UI shows consequences before applying.

## Drift / Reconciliation

External provider/runtime configuration can be observed and compared to AWP effective desired state. A mismatch is classified and linked to source ownership. AWP does not overwrite provider-owned configuration that is intentionally external without policy/Decision.

## Increment Realization

| Increment | Configuration realization |
|---|---|
| I0 | registry, scope resolution, validation, provenance, basic Settings/CLI. |
| I1 | execution/provider/account/workspace settings. |
| I2 | Planning/delivery defaults and participation mode. |
| I3–I8 | autonomy/CI/deployment/cluster/incident settings. |
| I9 | org/tenant quotas/retention and enterprise governance. |

## Current Implementation State

Target spec. Existing Overdeck JSON/files may be migration/reference evidence only.

## Deferred Realization

Rich schema-driven settings forms can evolve; configuration contract and provenance cannot.

## Temporary Dogfood Behavior

Some definitions may initially be edited via CLI/config file, but the same registry persists/evaluates them. No hidden second config system.

## Failure / Recovery

Invalid mutation is atomic/no-op. Provider apply failure preserves desired/current distinction and creates attention instead of lying that configuration took effect.

## UI Implications

Settings matrix is accessible at System/Project/Plan/Task scopes with search, inherited source, override indicator, locked explanation and effective consequence.

## Decisions / ADRs

Material precedence/security-ceiling changes require Decision.