RFC-0001: Lifecycle State Machines

Version: 0.2.1 | Status: normative | Phase: stable

1. Summary

[RFC-0001:C-SUMMARY] Summary (Informative)

This RFC defines state machines governing RFC, ADR, Work Item, and Clause lifecycles.

Since: v0.1.0

2. Specification

[RFC-0001:C-RFC-STATUS] RFC Status Transitions (Normative)

An RFC MUST have exactly one of the following status values:

1. draft — Initial state. The RFC is under development and not yet binding.
2. normative — The RFC defines required behavior. Implementations MUST conform. Normative RFCs MAY be amended via version bumping; amendments MUST include a changelog entry documenting the change.
3. deprecated — The RFC is no longer recommended. Existing conforming implementations MAY continue, but new implementations SHOULD NOT use this RFC.

Valid transitions:

• draft → normative (via finalize command)
• normative → deprecated (via deprecate command)

Invalid transitions (MUST be rejected):

• normative → draft (no “un-finalize”)
• deprecated → normative (no resurrection)
• deprecated → draft (no resurrection)
• Any skip (e.g., draft → deprecated directly)

Since: v0.1.0

[RFC-0001:C-RFC-PHASE] RFC Phase Transitions (Normative)

An RFC MUST have exactly one of the following phase values:

1. spec — Specification phase. The RFC text is being written. No implementation work.
2. impl — Implementation phase. Code is being written to conform to the RFC.
3. test — Testing phase. Implementation is complete; tests are being written and validated.
4. stable — Stable phase. Implementation and tests are complete. No further changes expected.

Valid transitions (forward only, via advance command):

• spec → impl
• impl → test
• test → stable

Invalid transitions (MUST be rejected):

• Any backward transition (e.g., impl → spec)
• Any skip (e.g., spec → test, spec → stable)
• stable → any (stable is terminal for phase)

Rationale: Phase discipline ensures specification precedes implementation, and testing validates implementation before stabilization.

Since: v0.1.0

[RFC-0001:C-WORK-STATUS] Work Item Status Transitions (Normative)

A Work Item MUST have exactly one of the following status values:

1. queue — Initial state. The work item is defined but not yet started.
2. active — The work item is currently being worked on.
3. done — The work item is complete. All acceptance criteria are satisfied.
4. cancelled — The work item was abandoned. No further work will be done.

Valid transitions (via move command):

• queue → active (start work)
• queue → cancelled (abandon before starting)
• active → done (complete work)
• active → cancelled (abandon in progress)

Invalid transitions (MUST be rejected):

• done → any (done is terminal)
• cancelled → any (cancelled is terminal)
• queue → done (cannot complete without being active)
• active → queue (no “un-start”)

Timestamp behavior:

• queue → active: Sets started date if not already set
• active → done: Sets completed date
• active → cancelled: Sets completed date

Since: v0.1.0

[RFC-0001:C-ADR-STATUS] ADR Status Transitions (Normative)

An ADR MUST have exactly one of the following status values:

1. proposed — Initial state. The decision is under consideration.
2. accepted — The decision has been accepted and is in effect.
3. superseded — The decision has been replaced by another ADR.

Valid transitions:

• proposed → accepted (via accept command)
• accepted → superseded (via supersede command, requires --by to specify replacement)

Invalid transitions (MUST be rejected):

• proposed → superseded (cannot supersede without first accepting)
• accepted → proposed (no “un-accept”)
• superseded → any (superseded is terminal)

When an ADR is superseded:

• The superseded_by field MUST be set to the ID of the replacing ADR
• The replacing ADR SHOULD reference the superseded ADR

Since: v0.1.0

[RFC-0001:C-CLAUSE-STATUS] Clause Status Transitions (Normative)

A Clause MUST have exactly one of the following status values:

1. active — Default state. The clause is in effect.
2. deprecated — The clause is no longer recommended but still valid.
3. superseded — The clause has been replaced by another clause.

Valid transitions:

• active → deprecated (via deprecate command)
• active → superseded (via supersede command, requires replacement clause)
• deprecated → superseded (already deprecated, now replaced)

Invalid transitions (MUST be rejected):

• deprecated → active (no resurrection)
• superseded → any (superseded is terminal)

When a clause is superseded:

• The superseded_by field MUST be set to the ID of the replacing clause
• The replacing clause SHOULD have a since field indicating the version it was introduced

Since: v0.1.0

[RFC-0001:C-GATE-CONDITIONS] Transition Gate Conditions (Normative)

Certain transitions have additional gate conditions beyond the state machine rules.

Work Item → done:

1. The work item MUST have at least one acceptance criterion defined
2. All acceptance criteria MUST have status “done” or “cancelled” (no “pending”)

Rationale: Prevents marking work as complete without defined success criteria.

RFC draft → normative:

• No additional gates (policy decision, not structural)

RFC phase spec → impl:

• RFC status SHOULD be normative (warning if draft)

Rationale: Implementation should follow finalized specification.

RFC phase impl → test:

• No additional gates

RFC phase test → stable:

• No additional gates (assumes tests are passing externally)

Future gates MAY be added via RFC amendment, but MUST NOT break existing valid workflows.

Since: v0.1.0

Changelog

v0.2.1 (2026-01-26)

Remove ADR reference from C-RFC-STATUS; RFCs are self-contained and should not reference ADRs

Added

• Inline amendment rule in C-RFC-STATUS clause (was referencing ADR-0016)

v0.2.0 (2026-01-19)

Clarify that normative RFCs may be amended via version bumping

v0.1.0 (2026-01-17)

Initial draft