# Spec status policy

> Source: https://openwop.dev/governance/spec-status/ · OpenWOP, the open-source protocol for multi-agent workflow orchestration.

The four labels below are the only status tiers a spec document under `spec/v2/` may carry. The same vocabulary applies to RFC sections and capability profile claims. They are deliberately ordered from most-stable (top) to most-fluid (bottom).

## The four tiers

### Stable

The wire surface is frozen under its major's compatibility contract. Required fields, endpoint contracts, event payloads, JSON Schema shapes, and SDK package names are locked. A change to a Stable surface is a **breaking change** and SHALL be deferred to the next major.

Hosts MAY advertise Stable surfaces via `/.well-known/openwop` without any profile gate. Conformance scenarios MUST be runnable against any Stable surface.

### Stabilizing

The required-field set and endpoint shapes are locked, but the document is still landing additive expansions — new optional fields, additional event-payload variants, broader behavior coverage. Implementations conforming to a Stabilizing surface SHOULD expect their conformance pass-rate to climb over time as new scenarios land, without their code needing to change.

A Stabilizing surface MAY graduate to Stable in a minor release once its conformance coverage stops moving. Hosts MAY advertise Stabilizing capabilities via `/.well-known/openwop` and MUST gate them behind a named profile.

### Draft

Section headings, broad surface shape, and the high-level wire contract are stable enough to review and prototype against, but field schemas and event payloads MAY shift on each weekly RFC roll-up. Draft documents typically have an open RFC governing the comment window.

Implementations against a Draft surface SHALL expect to make code changes when the surface graduates to Stabilizing or Stable. Hosts SHOULD NOT advertise Draft surfaces via `/.well-known/openwop` outside of explicit experimental opt-in profiles.

### Experimental

The document sketches an in-flight surface — direction set, but neither field shapes nor event payloads are locked. Anything inside an Experimental document MAY break across patch releases. Implementers SHOULD pin only to what is explicitly written and assume gaps everywhere else.

Hosts MUST NOT advertise an Experimental capability outside of an explicit opt-in profile, and conformance scenarios for an Experimental surface SHALL run as `it.todo` until the surface graduates.

## Where the label appears

Every spec document under `spec/v2/` carries a single status banner at the top of the file. It names the owning RFC(s), and most core docs follow it with the families the doc is the normative home for:

```
> **Status: <Tier> · RFC <NNNN>.**
> **Normative home:** `<family>`.
```

The site shows this banner at the top of each document page and on its card in the [`/spec/v2/`](https://openwop.dev/spec/v2/) index.

## Promotion process

A spec document graduates between tiers via an RFC and a CHANGELOG entry, never silently:

1. **Experimental → Draft** — landed via an open RFC that opens a comment window. Field shapes are negotiable inside the window.
2. **Draft → Stabilizing** — RFC closes; the comment window expires; required-field set and endpoint shapes lock. Document is editable additively.
3. **Stabilizing → Stable** — every required-field gap closes, conformance coverage stabilizes, and the steward declares the surface frozen for that major. Demotion from Stable inside a major requires a safety-fix RFC under [COMPATIBILITY.md §3](https://github.com/openwop/openwop/blob/main/COMPATIBILITY.md).

A document MAY skip tiers (e.g., a fully-specified surface lands directly at Stable inside an existing RFC), but never silently. The CHANGELOG entry SHALL name the new tier.

## Acceptance criteria

A spec document SHALL be at the **Stable** tier if and only if:

- Required-field set is closed and conformance scenarios cover every required field.
- Endpoint contracts are present in `api/v2/openapi.yaml`.
- Event payloads are present in `api/v2/asyncapi.yaml` and `schemas/`.
- The corresponding capability profile is advertisable in the `/.well-known/openwop` document without an opt-in flag.
- No `it.todo` blocks against the document remain in `@openwop/openwop-conformance` outside of an explicit profile gate.

A document failing any of these criteria SHALL be labelled **Stabilizing** at most.