# AWP Full Specification Ratification

**Date:** 2026-08-20  
**Status:** **RATIFIED / BINDING / COMPLETION GATE CLOSED**  
**Authority:** Owner-approved product-development policy.  
**Completion record:** [`AWP-SPECIFICATION-FINALIZATION-2026-08-20.md`](AWP-SPECIFICATION-FINALIZATION-2026-08-20.md)

## 1. Ratified Decision

AWP uses **full-specification-first, incremental-realization**.

```text
FULL TARGET SPECIFICATION
  complete product / architecture / domain / workflow / UI / schema intent
        ↓
OWNER-APPROVED HIGH-FIDELITY FOR CURRENT USER-FACING INCREMENT
        ↓
INCREMENTAL IMPLEMENTATION
  I0 -> I1 -> I2 -> ... -> I9
        ↓
DOGFOOD / LEARN / EXPLICITLY AMEND SPECS WHEN EVIDENCE CHANGES DESIGN
```

Increment boundaries decide **when capability becomes operational**, not when AWP is allowed to define the target contract.

## 2. Why This Is Binding

AWP exists partly because the Overdeck experiment accumulated architecture/UX drift while implementation moved faster than durable product intent.

The failure mode to prevent is:

```text
local implementation shortcut
 -> next increment treats it as precedent
 -> original intent disappears from active context
 -> later seams bend around accidental architecture
 -> product/UX/architecture diverge without an explicit Decision
```

AWP therefore pays the up-front specification/design cost and allows changes only through evidence-backed amendment.

## 3. What “Full Specification” Means

Where material, the canonical specs define:

```text
purpose / scope / non-goals
terminology
primitives / stable IDs / relationships
state machines / commands / queries
transaction boundaries
business events / audit
trust / authorization / credentials
configuration / inheritance / policy
provider / adapter seams
reconciliation / idempotency / retry / cancellation
failure / recovery behavior
compatibility / migration expectations
observability / realtime implications
API / CLI / MCP implications
UI journeys / states / responsiveness / accessibility / URL truth
acceptance requirements
Decision / ADR links
Increment Realization
```

Implementation-local details may remain open only when they can change behind an already-defined seam without changing product behavior, ownership, trust, compatibility, workflow or approved page behavior.

## 4. Target State vs Increment Realization

Every canonical specification distinguishes:

```text
Target State
Invariants From Day 1
Increment Realization
Current Implementation State
Deferred Realization
Temporary Dogfood Behavior
Decisions / ADRs
```

An early implementation is a subset of the final model, not a throwaway model.

## 5. Canonical Increment Order

Implementation authority remains [`AWP-INCREMENTAL-DELIVERY-PLAN.md`](AWP-INCREMENTAL-DELIVERY-PLAN.md).

```text
I0  Foundation / self-hosting substrate
I1  Project + ProjectVision + Goal -> Plan -> Task/Queue -> FactoryRun -> AgentRun/Attempt -> ChangeSet -> Review -> trusted Merge
I2  Real Planning + full Goal management/readiness
I3  Decisions/Approvals/autonomy + Project Manager + Search
I4  full Factory/Agent observability + AWP Advisor
I5  CI control plane
I6  Release / Deployment
I7  Cluster product surface
I8  self-healing Incident / Resolver
I9  enterprise + formal reliability/SLO
```

No implementation agent may pull later capability forward merely because the target spec already exists.

## 6. Human Specification Authority

Canonical Markdown remains implementation/diff authority. Human HTML companions and indexes are required by [`../specs/SPEC-PRESENTATION-STANDARD.md`](../specs/SPEC-PRESENTATION-STANDARD.md) so product/architecture intent is navigable by humans as well as agents.

The specification root is [`../specs/INDEX.html`](../specs/INDEX.html).

## 7. UI / High-Fidelity Policy

Full UI/page behavior is specified before implementation.

For user-facing states:

```text
full product IA                         specified early
shared visual language                  fixed before first UI implementation
material future placement               fixed where layout-relevant
exact current-increment high-fi          owner-approved before implementation
failure/waiting/permission variants      designed before implementation
```

Approved high-fidelity becomes binding visual authority for that lifecycle state.

For I1 the full U1–U6 set is now owner-approved/final.

## 8. Anti-Drift Decision Rule

If implementation evidence conflicts with approved target authority:

```text
new evidence / constraint
 -> Decision opened or superseded
 -> impact affected specs/mockups/increment boundary
 -> amend canonical target authority
 -> implementation follows amended authority
```

Never silently make code the new design authority.

## 9. Full-Specification Completion Gate — CLOSED

```text
[✓] full architecture target specification set exists
[✓] full domain target specification set exists
[✓] full major workflow specification set exists
[✓] full UI/page target specification set exists
[✓] schemas/contracts/adapters define ownership/compatibility boundaries
[✓] active canonical specification presentation/index coverage exists
[✓] Increment Realization is explicit
[✓] major primitive/flow cross-links exist
[✓] material Decisions/ADRs are linked
[✓] temporary/dogfood shortcuts are explicit
[✓] I0/I1 implementation boundaries are unambiguous
[✓] I1 U1–U6 visual states are owner-approved
```

**Result: GREEN.**

This gate concerns specification/design completeness. It does not assert live provider/cluster/runtime proofs are green.

## 10. Remaining Evidence Gates

The following remain implementation/preflight work rather than specification work:

```text
exact Platform consumer pins/tests
exact current Overdeck source harvest where relevant
Subrouter adapter proof
DBOS failure/recovery proof
K3s Workspace/WIP proof
gVisor / Dev Container compatibility proof
Fabro / ACP runtime mapping proof
ARC runner E2E
trusted publication/merge E2E
executable security mitigations
```

A blocked environment is never interpreted as a successful proof.

## 11. Per-Increment Design Complete

The normal per-increment cycle remains:

```text
full target spec already exists
 -> confirm increment boundary
 -> approve exact high-fi states
 -> conformance review
 -> implement
 -> focused verification
 -> dogfood
```

For I1, Design Complete is now **GREEN**.

## 12. Parallel Implementation

Implementation concurrency is governed by [`AWP-I0-I1-PARALLEL-IMPLEMENTATION-PLAN.md`](AWP-I0-I1-PARALLEL-IMPLEMENTATION-PLAN.md).

The first development conversation starts I0-A0 Bootstrap using [`AWP-I0-DEVELOPMENT-AGENT-1-PROMPT.md`](AWP-I0-DEVELOPMENT-AGENT-1-PROMPT.md).

A0 lands convergence commit C0 before provider/execution/UI code lanes branch. The source-harvest evidence lane may run immediately in parallel because it owns documentation/evidence only.

## 13. Ratified I01-D1 Replacement

`I01-D1R` remains approved:

> **Full canonical AWP specifications are written before implementation materially begins. Increment 0..9 define realization timing, not specification timing. Every early implementation conforms to the final seams/contracts already recorded in the specification set.**

## 14. Current Phase

```text
specification authoring/reconciliation   COMPLETE
I1 U1–U6 high-fidelity approval         COMPLETE
implementation planning                  COMPLETE
next                                     I0 implementation
```

No further serial product-design interview is required unless implementation uncovers a genuine owner-level contradiction.