# Configuration and Policy

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

## Target State

Configuration and policy are typed, inherited and fully inspectable through AWP. The hierarchy is:

```text
System -> Project -> Plan -> Task -> Run
```

Ordinary settings may override according to schema. Security/capability ceilings only narrow downstream. Every effective value is explainable by provenance.

## Invariants From Day 1

- every setting has schema/type/default/validation/description and scope rules;
- UI can display current value, inherited source and override status;
- secrets are never ordinary configuration values;
- immutable/unsafe-to-edit settings are visible read-only with explanation;
- lower scopes cannot broaden security/capability ceilings;
- effective configuration is resolved deterministically and persisted/snapshotted where execution reproducibility requires it;
- configuration mutation is audited and can invalidate dependent readiness/evidence where material;
- provider-native config does not leak into domain objects without adapter-owned mapping.

## Configuration Model

Conceptually:

```text
ConfigurationDefinition
  key
  type/schema
  default
  allowedScopes
  mergeStrategy
  sensitive?  # sensitive values must be references
  mutable?
  restart/replan implications
  description

ConfigurationValue
  scopeType/scopeId
  key
  value/reference
  source
  revision
```

Effective resolution returns both value and provenance chain.

## Policy Model

Policy governs permission/progression/approval/autonomy rather than ordinary preferences.

Examples:

- who may merge;
- when human approval is required;
- whether security findings block;
- allowed execution profiles/providers/models;
- deployment promotion requirements;
- maximum capability/credential scope.

The user-facing 0–100 autonomy control is a preset/editor over concrete rules, not the policy engine itself.

## Autonomy Hierarchy

```text
System policy ceiling
  ↓
Project autonomy/defaults
  ↓
Plan policy delta
  ↓
Task/run narrowing
```

Policy evaluation produces explicit reason/evidence and required next action. Resolver models may decide only within configured authority; they cannot invent permission.

## Configuration Drift

Provider/runtime configuration is reconciled against AWP desired/effective configuration. Drift is classified:

```text
benign observed difference
expected external ownership
reconcilable drift
blocking conflict
security violation
```

Blocking/security drift becomes Finding/Incident and prevents unsafe progression.

## Settings UI Requirement

All configuration that is product-relevant and safe to expose is visible/editable at its permitted scopes. The UI shows:

- effective value;
- source scope;
- inherited chain;
- validation and consequences;
- locked/ceiling reason;
- pending/restart/replan effect;
- reset-to-inherited action.

## Increment Realization

| Increment | Configuration/policy realization |
|---|---|
| I0 | registry/schema/effective resolution, project/run execution settings, security ceilings. |
| I1 | provider/account/model/workspace execution configuration. |
| I2 | Planning participation/defaults, Quality/CI/delivery profiles. |
| I3 | generic autonomy/HITL/Approval policy UX. |
| I5–I8 | CI, deployment, cluster, incident policy families. |
| I9 | org/tenant policy, quotas, retention and enterprise governance. |

## Current Implementation State

Target configuration model replaces ad-hoc Overdeck JSON/config drift patterns; existing files may be import/reference sources only.

## Deferred Realization

No generic external policy engine is baseline. Add OPA/Cedar-like infrastructure only if concrete policy complexity justifies an adapter/provider boundary.

## Temporary Dogfood Behavior

Some values may initially be set through config files/CLI before corresponding Settings UI exists, but they still use typed definitions/provenance and cannot create a second configuration authority.

## Decisions / ADRs

Material scope/precedence/security-ceiling changes are Decisions because they affect future behavior across increments.