Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

RFC-0001: Lifecycle State Machines

Version: 0.1.0 | Status: normative | Phase: stable

1. Summary

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

This RFC defines the lifecycle state machines for all governed artifacts in govctl.

Each artifact type has a finite state machine that governs its lifecycle:

  • RFC: status (draft/normative/deprecated) and phase (spec/impl/test/stable)
  • Work Item: status (queue/active/done/cancelled)
  • ADR: status (proposed/accepted/superseded)
  • Clause: status (active/deprecated/superseded)

Key principles:

  1. State machines are acyclic (no going backward)
  2. Terminal states are final (done, cancelled, superseded, stable)
  3. Transitions may have gate conditions beyond state validity
  4. All transitions are explicit commands (no implicit state changes)

This specification documents what is already implemented in govctl v0.1.0.

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.
  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.1.0 (2026-01-17)

Initial draft