# ADR Lifecycle and Status Mapping

Status: Active
Last reviewed: 2026-01-30
Authority: Canon (defines ADR lifecycle states, pre-release identifiers, and closeout-to-status mapping)

This document canonizes ADR lifecycle states and their relationship to Gate 5 closeout attestation.
For gate definitions, see [charter.md](charter.md). For closeout ceremony behavior, see [audit-protocol.md](audit-protocol.md).

---

## ADR Lifecycle States

An ADR progresses through these states:

| State | Meaning | Transition Trigger |
|-------|---------|-------------------|
| **Pool** | Planned ADR awaiting prioritization; lightweight intent only | Author identifies future work need |
| **Draft** | ADR being authored; not yet ready for review | ADR pulled from pool; author creates full structure |
| **Proposed** | ADR submitted for review; awaiting acceptance | Author completes evaluation and declares ready for review |
| **Accepted** | ADR approved; implementation work may begin | Human accepts the proposal |
| **Completed** | Implementation finished; Gate 5 attestation received | Human attests "Completed" or "Completed — Partial" |
| **Validated** | Post-attestation audit completed (Phase 2) | Audit passes and reconciliation recorded |
| **Superseded** | Replaced by a newer ADR | New ADR explicitly supersedes this one |
| **Abandoned** | Work stopped; ADR will not be completed | Human attests "Dropped" or declares abandonment |

### Lifecycle Diagram

```text
Pool → Draft → Proposed → Accepted → [implementation] → Closeout Ceremony → Completed → Validated
  │                                                                        → Abandoned (if Dropped)
  │                                                      ↓
  │                                                 Superseded (if replaced by new ADR)
  │
  └── (may remain in pool indefinitely until prioritized or dropped)
```

---

## Pre-Release Identifier Scheme (SemVer Compliant)

During development (0.y.z) and post-release (1.0.0+), SemVer pre-release identifiers provide
a unified namespace for tracking work items. The format is:

```text
{major}.{minor}.{patch}[-{type}.{identifier}]
```

### Identifier Types

| Type | Purpose | Example |
|------|---------|---------|
| `pool.{slug}` | Planned ADR in pool, awaiting prioritization | `0.2.0-pool.forecaster-core` |
| `obpi.{nn}` | OBPI brief in progress under an ADR | `0.1.15-obpi.03` |
| `ghi.{nn}` | GitHub Issue discovered during work | `0.1.15-ghi.67` |

### Precedence

Per SemVer, pre-release versions have **lower precedence** than the associated normal version:

```text
0.1.15-obpi.01 < 0.1.15-obpi.02 < 0.1.15-ghi.67 < 0.1.15
```

When an ADR completes (e.g., `0.1.15`), all work-item identifiers (`-obpi.*`, `-ghi.*`) are
"rolled up" into the completed version.

### Examples

**Pre-1.0.0 (initial development):**

| Version | Meaning |
|---------|---------|
| `0.1.15` | ADR-0.1.15 completed |
| `0.1.15-obpi.01` | OBPI-0.1.15-01 in progress |
| `0.1.15-ghi.67` | GHI #67 discovered during 0.1.15 work |
| `0.2.0-pool.exog-pipeline` | ADR planned for 0.2.x, not yet started |

**Post-1.0.0 (stable API):**

| Version | Meaning |
|---------|---------|
| `1.2.3` | Current stable release |
| `1.2.4-obpi.01` | Patch-level work in progress |
| `1.3.0-pool.forecaster` | Minor-level feature in planning pool |
| `2.0.0-pool.breaking-change` | Major-level breaking change planned |

### Pool Artifacts

Pool ADRs live in `docs/design/adr/pool/` with pre-release identifiers:

```text
docs/design/adr/pool/
  ADR-0.2.0-pool.exog-pipeline.md       # lightweight intent only
  ADR-0.2.0-pool.forecaster-core.md
  ADR-1.3.0-pool.scheduler-cadence.md
```

**Pool Status Constraint (Binding):**

ADRs in the `docs/design/adr/pool/` directory may **ONLY** have status `Pool`.

| Rule | Enforcement |
|------|-------------|
| Pool ADRs have status `Pool` only | No other status permitted while in pool/ |
| Pool ADRs are lightweight | Intent only; no OBPI briefs required |
| Pool ADRs cannot be Proposed/Accepted | Must be pulled from pool first |
| Pool directory is the only valid location for Pool status | ADRs outside pool/ cannot have status Pool |

**Rationale:** The pool is a backlog of planned work, not active governance artifacts.
Pool ADRs await prioritization and do not participate in the gate system until pulled.

When pulled from pool:

1. Assign the next available version number (e.g., `0.2.1`)
2. Create full ADR folder structure under `docs/design/adr/adr-X.Y.x/`
3. Change status to `Draft` (or `Proposed` if ready for review)
4. Write OBPI briefs (required before `Accepted`)
5. Delete or archive the pool file

### Pool Promotion Tooling

Use the canonical promotion command:

```bash
uv run gz adr promote ADR-pool.<slug> --semver X.Y.Z [--dry-run]
```

The command enforces protocol and writes lineage evidence:

- Creates promoted ADR package path by SemVer bucket (`foundation/`, `pre-release/`, `<major>.0/`)
- Requires actionable `## Target Scope` bullets and converts them into the promoted ADR checklist
- Creates matching OBPI briefs in the promoted ADR `obpis/` directory
- Marks pool source file as archived context (`status: Superseded`, `promoted_to: ADR-X.Y.Z-slug`)
- Appends `artifact_renamed` ledger event with reason `pool_promotion`
- Appends `obpi_created` events for the generated briefs

---

## Closeout Attestation to Status Mapping

When a human provides Gate 5 attestation, the ADR status updates as follows:

| Closeout Attestation | ADR Status | Notes |
|---------------------|------------|-------|
| **Completed** | Completed | All claims verified; work finished |
| **Completed — Partial: [reason]** | Completed | Deferrals documented in ADR Consequences section; follow-on ADRs created for deferred scope |
| **Dropped — [reason]** | Abandoned | Rationale recorded; ADR does not count toward roadmap |

---

## Audit Completion to Status Mapping

| Audit Outcome | ADR Status | Notes |
|--------------|------------|-------|
| Audit passes | Validated | Post-closeout reconciliation complete |
| Audit pending or failing | Completed | Remains in Phase 1 until resolved |

---

## State Transition Rules

1. **Pool → Draft**: ADR pulled from pool; author creates full structure in `adr-X.Y.x/`
2. **Draft → Proposed**: Author runs ADR evaluation, records `EVALUATION_SCORECARD.md`, and determines the ADR is ready for review
3. **Proposed → Accepted**: Human reviews and accepts the proposal for implementation
4. **Accepted → Completed**: Human provides "Completed" or "Completed — Partial" attestation via closeout ceremony
5. **Accepted → Abandoned**: Human provides "Dropped" attestation or explicitly abandons work
6. **Any → Superseded**: A new ADR explicitly declares it supersedes this one (add `Superseded-By: ADR-X.Y.Z` to metadata)
7. **Completed → Validated**: Audit passes and reconciliation recorded

**Pool-specific constraints:**

- Pool ADRs cannot skip Draft (must be pulled and structured first)
- Pool ADRs may be abandoned directly (Pool → Abandoned) if deprioritized
- Pool is the only status valid in `pool/` directory; all other statuses require `adr-X.Y.x/`

---

## OBPI Completeness Requirement (Canonical)

**Binding rule: The ADR Feature Checklist and the OBPI Briefs MUST remain in 1:1 synchronization. NO DRIFT PERMITTED.**

Before an ADR transitions to **Accepted** status:

-   **1:1 Mapping**: Each numbered checklist item in the ADR's Feature Checklist MUST have exactly one corresponding OBPI brief file in the `briefs/` directory.
-   **Identification**: Each brief MUST follow naming: `OBPI-{semver}-{nn}-{slug}.md`.
-   **Linkage**: Each brief MUST reference its parent ADR and the specific checklist item it fulfills.
-   **Synchronized Intent**: The objective and acceptance criteria of the brief MUST match the intent of the checklist item.

### OBPI Decomposition Protocol (Matrix of Four Overlay)

To maximize granularity and ensure incremental delivery, the ADR Feature Checklist MUST be developed using a two-step decomposition protocol:

1.  **Step 1: Baseline Structural Template (Rule of Three)**: Complex ADRs are initially scaffolded into three baseline checklist items: Registry/Interface, Core Execution, and Lifecycle/Operations.
2.  **Step 2: Refining Overlay (Matrix of Four)**: Apply the principles defined in the [OBPI Decomposition Matrix](obpi-decomposition-matrix.md) (Single-Narrative, Testability, State Anchor, Surface Boundary) to each baseline unit. If a unit violates a principle, it MUST be further decomposed into multiple checklist items.

**Rationale:** The Feature Checklist is the governance contract for the ADR. OBPIs are the execution units for that contract. High-granularity decomposition prevents "god-object" briefs and oversized verification batches. Drift between the checklist and the briefs creates un-auditable scope and violates the principle of layered trust.

**Enforcement:** The `gz-adr-create`, `gz-plan`, and `gz-adr-eval` skills enforce this 1:1 synchronization, quality review, and the two-step protocol during the spec/decomposition phase. Automated verification (e.g., `gz validate`) that fails the checklist-to-brief count check is a blocking governance failure.

**Anti-pattern:** ADR tables listing OBPIs as "Pending" with no actual brief files. This is a governance violation. All briefs must exist as files before the ADR is Accepted.

---

## Deprecated Terms

The following terms have been used historically but are **not canonical**:

| Term | Disposition |
|------|-------------|
| Deprecated | Use "Superseded" with rationale, or "Abandoned" if no replacement |
| Pending | Use "Proposed" or "Accepted" depending on approval state |
| Retired | Use "Superseded" with backlink to replacement |
| Completed + Validated | Use "Validated" (legacy combined status) |

---

## ADR Status Table

The authoritative ADR status table lives at [adr-status.md](adr-status.md) (colocated in GovZero).

That table MUST use only the lifecycle states defined in this document.
Status values in that table are derived from this canon; if conflict exists, this document governs.

---

## ADR Series and Release Tagging

ADRs are organized into series by their minor version number. Each series has distinct governance characteristics.

### Series Classification

| Series | Name | Purpose | Release Tag Behavior |
|--------|------|---------|---------------------|
| **0.0.x** | Foundation | Infrastructure, governance, tooling | No release tags created |
| **0.1.x+** | Feature | User-facing capability, external contracts | Release tags created on validation |

**Foundation series (0.0.x):**

- Establishes project infrastructure, governance framework, and developer tooling
- Changes are internal/structural and do not constitute user-facing releases
- Validated foundation ADRs contribute to project maturity but do not trigger version bumps
- Example: ADR-0.0.21 (GovZero Layered Trust) — governance infrastructure, not a release

**Feature series (0.1.x and beyond):**

- Introduces user-facing capability, external API changes, or observable behavior changes
- Each validated ADR in a feature series represents a releasable increment
- Release tags track the highest validated feature-series ADR

### Release Tag Rule (Binding)

**The release tag SHALL be the highest validated non-foundation ADR.**

```text
Release Tag = v{highest validated ADR where series ≠ 0.0.x}
```

| Scenario | Highest Validated | Release Tag |
|----------|-------------------|-------------|
| ADR-0.1.14 validated | 0.1.14 | v0.1.14 |
| ADR-0.0.25 validated (foundation) | 0.1.14 (unchanged) | v0.1.14 (no change) |
| ADR-0.1.15 validated | 0.1.15 | v0.1.15 |

**Backfill validations:** When earlier ADRs are validated after later ones (e.g., 0.1.12 validated after 0.1.14), no new release tag is created — the release already advanced.

### Agent Enforcement

When validating an ADR, agents MUST:

1. Check if the ADR is in the foundation series (0.0.x)
2. If foundation: complete validation, no release tag action
3. If feature series: compare against current highest validated feature ADR
4. If this ADR > current highest: create release tag `v{ADR version}`
5. If this ADR ≤ current highest: no release tag action (backfill case)

---

## References

- Gate definitions: [charter.md](charter.md)
- Closeout ceremony: [audit-protocol.md](audit-protocol.md)
- Disposition rubric: [../ADR_DISPOSITION_RUBRIC.md](../ADR_DISPOSITION_RUBRIC.md)
- ADR status table: [adr-status.md](adr-status.md)
- Release doctrine: [releases/README.md](releases/README.md)
