# Project Decision Log UI

**Status:** Approved target-state baseline  
**Full product activation:** I3; Planning decisions exist structurally from I2.  
**Purpose:** Make material project decisions, rationale, authority, history and downstream impact easy to inspect so project intent cannot disappear into chat logs or old plans.

## Target State

The Decision Log is a human projection over canonical `Decision` records. It is not a separate persistence model and does not compete with ADRs.

Primary questions:

```text
What important choices define this Project?
Who/what made each choice?
Why?
What alternatives/evidence were considered?
What does the decision affect?
Is it still current?
What superseded it?
What needs a decision now?
```

## Primary Users / Jobs

- project owner: recover why consequential product/technical choices were made and change them safely when needed;
- technical/delivery lead: inspect current architecture/quality/delivery policy and downstream impact;
- reviewer/agent: resolve the current authoritative Decision instead of inferring intent from chat/commit history.

## Entry Points

- `Project -> Decisions`;
- global search/command;
- Planning context/Decision references;
- Architecture/ADR links;
- Work/Review/CI/Release/Deployment impact links;
- Needs Your Attention for unresolved OwnerRequired/PolicyRequired decisions.

Exit points include the affected Plan/Task/spec/config/CI/delivery artifact, related Approval/ADR, or superseding Decision flow. Back navigation preserves filters/selected Decision.

## User Journeys

### J1 — Recover project intent

```text
open Decision Log
 -> filter/group by category/current status
 -> select Decision
 -> inspect authority + rationale + alternatives + evidence
 -> inspect affected artifacts
 -> follow linked spec/work/ADR if needed
```

### J2 — Make a required Decision

```text
Needs decision
 -> understand consequence + blocking gate + recommendation/confidence
 -> compare credible alternatives
 -> choose/accept
 -> durable Decision recorded with actor/evidence
 -> affected artifacts/readiness re-evaluated
 -> planner/workflow resumes
```

### J3 — Supersede rather than edit history

```text
current Decision no longer fits
 -> Propose change
 -> new recommendation/alternatives/evidence
 -> accept new Decision
 -> old Decision marked superseded, never rewritten
 -> affected specs/work/config become current or stale explicitly
```

### J4 — Resolve conflict during existing-project onboarding

```text
observed current != documented intended != desired
 -> open linked Decision/Finding
 -> inspect provenance of each truth claim
 -> owner/AWP resolves according to authority class
 -> resulting Decision feeds Planning/Project defaults
```

## Information Architecture

```text
Decision Log
  Current
  Needs decision
  Deferred
  History / superseded

Filters
  category
  authority / participation class
  scope
  Plan
  status
  changed recently

Decision detail
  subject + selected value
  status / scope / category
  decided by / decided at
  participation class / authority
  confidence + basis
  rationale
  alternatives considered
  evidence / assumptions
  consequences
  what would change the recommendation
  affected specs/work/config/contracts/delivery
  supersedes / superseded by
  related ADR when architecture-significant
```

## Collection Presentation

Default list is grouped/scannable by category and current status rather than chronological chat order.

Example:

```text
Architecture
  D-041  PostgreSQL is authoritative product state
         Accepted · Project-wide · owner/AWP authority shown

Quality
  D-052  CUJ-first affected verification
         Accepted · Project-wide

Plan 18
  D-071  Preserve legacy API during migration
         Accepted · Plan scope

Deployment
  D-083  Use provider X
         Accepted · supersedes D-034
```

The user can switch to chronological history when investigating change over time.

## Authority Visibility

The UI must never imply the owner personally chose something that AWP decided under delegated authority.

Expose:

```text
OwnerRequired     owner chose / must choose
DelegableExpert   AWP recommendation/decision + confidence/basis
PolicyRequired    protected consent/approval relationship
```

`Decision`, `Approval` and `Review` are visually and semantically distinct.

## Supersession

Accepted decisions are historical facts. Editing a material accepted decision creates/proposes a new Decision and supersession relationship rather than mutating history.

The UI shows:

```text
D-034  superseded
   ↓ replaced by
D-083  current
```

with reason/evidence for the change.

## Impact and Staleness

Decision detail exposes affected artifacts and current impact state:

```text
Specs
PlanRevision
Tasks/work
CIInvariant
Configuration/defaults
contracts/APIs
Release/Deployment policy
mockups
```

When a Decision changes, affected items can become stale/needs-review. The user can inspect exactly what requires reconciliation.

## ADR Projection

Architecture-significant current/history decisions link to generated/maintained ADR projection. ADR is a readable architecture-history artifact, not a second place to edit the current choice.

## Data / Source of Truth

Canonical `Decision` records, authority/participation class, evidence references, supersession and impact relations are authoritative. ADRs, Planning context and UI collections are projections. Conversation text or old plan prose never overrides a newer accepted Decision without explicit supersession.

## Actions

Possible contextual primary actions:

```text
Decide / Accept recommendation
Review deferred decision
Propose change
Compare alternatives
Open affected artifact
```

Do not show `Edit` on accepted history if it would imply mutation rather than supersession.

## Authorization / Mutation Safety

OwnerRequired choices require the owner; DelegableExpert follows configured planner/autonomy authority; PolicyRequired protected action links to Approval. Decision creation/supersession uses revision/idempotency protection and immutable history. Duplicate submission cannot create competing accidental Decisions for the same active proposal. Stale context forces review before accept.

## Complete States

### Empty

Explain that no material Decisions have been recorded yet; do not encourage recording trivial choices.

### Loading

Preserve collection/detail geometry.

### Error / Stale

Keep last-known Decision history readable with freshness warning. New Decision/protected action requires live authoritative connection.

### Needs decision

Show consequence, blocking gate and why the owner/policy is required. One primary decision action.

## URL Truth

Persist Project, status/category/scope filters, search, selected Decision and history/current view in the URL where practical. Individual Decisions have stable deep links.

## Accessibility

- current/superseded status not color-only;
- alternative comparison keyboard-operable;
- focus returns predictably from detail drawers/modals;
- impact graph/list has a non-visual textual equivalent;
- confidence is expressed in text, not only icon/color.

## Invariants From Day 1

- accepted Decision history is immutable;
- material change creates supersession, not edit-in-place;
- actor/authority/evidence are always attributable;
- Decision, Approval and Review never collapse into one generic status;
- affected artifacts can be stale explicitly rather than silently rewritten;
- the current Decision can be found without reconstructing chat history.

## Increment Realization

| Increment | Decision Log |
|---|---|
| I2 | Planning surfaces can expose Planning decisions and their rationale. |
| I3 | dedicated project Decision Log, generic supersession/impact/Approval integration. |
| I4–I8 | decisions from Factory/CI/Delivery/Cluster/Incident domains become richer linked sources. |
| I9 | organization/tenant/governance exports where required. |

## Current Implementation State

Target page spec only.

## Deferred Realization

Portfolio-wide enterprise decision governance and exports are I9 concerns, not dogfood blockers.

## Temporary Dogfood Behavior

Before the dedicated I3 screen exists, Planning/Project context may show relevant Decision summaries using the same canonical records. Do not create Markdown-only decisions that later require migration.

## Related Specs

- `../domains/approvals-decisions.md`
- `planning.md`
- `approval.md`
- `project.md`
- `INDEX.md`

## Decisions / ADRs

Architecture-significant Decisions project into ADRs according to the architecture/spec governance rules. ADR is never a second editable authority. Decision participation/confidence rules come from the Planning/Decision specs.

## Visual Mockup Authority

No dedicated Decision Log high-fi is approved yet. Planning may show canonical Decision summaries earlier; the I3 collection/detail, supersession, Needs-decision and impact states require approval before dedicated page implementation.

## Acceptance

A user can find the reason for a consequential project choice, identify who/what decided it, inspect rejected alternatives/evidence and downstream impact, and understand whether it is current or superseded without reconstructing a conversation.