# Approvals and Decisions Domain

**Status:** Approved target-state baseline  
**Decision semantics used:** Planning I2  
**Generic product activation:** I3.

## Target State

`Decision` is a first-class cross-domain primitive preserving material choices; `Approval` is a distinct authorization primitive. A Project Decision Log is a projection over Decisions, not a separate truth store.

```text
Decision
  why/what/alternatives/consequences/evidence
  -> may influence Plan/Task/architecture/policy/release/etc.

Approval
  who authorized/denied what action under which policy/context

Architecture-significant Decision
  -> ADR projection
```

## Decision Qualification

Create a Decision when changing the answer later would materially affect:

```text
product/scope
behavior/UX
architecture
security/privacy
quality/testing
contracts/compatibility
cost/reliability
CI/CD/operations
policy/defaults
or downstream work/artifacts
```

Do not flood the log with routine local implementation trivia.

## Decision Contract

Target fields:

```text
id
projectId
scopeType/scopeId
subject
category
status: proposed | accepted | rejected | deferred | superseded
participationClass?
decision/value
rationale
alternativesConsidered[]
consequences[]
assumptions[]
evidence[]
confidence
reversibility
decidedBy/authority provenance
decidedAt
supersedesDecisionId?
affectedArtifacts/specs/work/contracts/configuration[]
firstRealizedInIncrement?
```

Accepted history is immutable. Change creates a newer Decision that supersedes it.

## Approval Contract

Target fields:

```text
id
projectId
scope/action/target
requestedBy
requiredByPolicy/gate
approver Principal or policy authority
disposition: pending | approved | denied | expired | cancelled
reason/conditions
requestedAt/decidedAt/expiresAt?
context revision / candidate identity
```

Approval binds to exact relevant revision/context. Candidate/policy material change may invalidate/require new Approval.

## Invariants From Day 1

- Decision and Approval are not synonyms;
- accepted Decision is never silently rewritten;
- supersession preserves links/history;
- owner-vs-delegated-vs-policy authority provenance is explicit;
- dependent specs/artifacts/work can become stale when a Decision changes;
- architecture Decisions can generate ADRs but ADR is projection/history, not competing current spec;
- review agents and planners can retrieve applicable accepted Decisions;
- Approval cannot authorize beyond Principal/security capability ceiling;
- expired/stale Approval never silently remains valid.

## Project Decision Log

Human view grouped/filterable by category/scope/status/increment, showing current accepted Decisions and superseded history. It answers:

```text
What did we decide?
Why?
Who/what decided?
What alternatives were rejected?
What evidence/confidence supported it?
What depends on it?
What superseded it?
```

## Impact Propagation

When a Decision reopens/supersedes:

```text
identify affected specs/artifacts/work/config/contracts
 -> mark stale/needs review where material
 -> re-evaluate Planning/readiness/evidence/gates
 -> update Increment Realization if timing changed
```

No automatic destructive rewrite of dependent state.

## ADR Projection

Architecture-significant accepted Decisions project to ADR records with Context/Decision/Consequences/Alternatives/Supersession links. Canonical architecture spec represents current state; ADR preserves why/history.

## Increment Realization

| Increment | Realization |
|---|---|
| I1 | narrow merge/security approvals where mandatory; underlying Decision model can exist as needed. |
| I2 | Planning Decisions/deferrals/defaults use shared primitive. |
| I3 | generic Decision Log, Approval/HITL/autonomy productization and ADR projection. |
| I5–I9 | CI/release/deployment/incident/enterprise Decisions use same primitive. |

## Current Implementation State

Target spec. The durable planning decision register in docs is historical design evidence; product primitive activates according to matrix.

## Deferred Realization

Cross-project organization Decision governance is I9. It extends, not replaces, project-scoped Decision identity.

## Temporary Dogfood Behavior

Before Decision Log UI, accepted project Decisions may be persisted/exposed through Planning/spec docs/CLI, but must retain canonical IDs/provenance rather than chat-only memory.

## Failure / Recovery

Concurrent Decision edits use revisions/conflict handling. Approval request/decision is transactional and idempotent; external notification failure does not lose Approval state.

## UI Implications

Decision Log is readable, concise and linked to affected specs/work. Approval UI has one primary decision action, clear consequence, evidence and expiry/context.

## Decisions / ADRs

This primitive itself is an accepted product decision intended to prevent vision/design drift.