RFC-0001: Lifecycle State Machines

Version: 0.3.0 | 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, including the additional transition gates that control when work may be treated as complete.

Tags: lifecycle

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)

Tags: lifecycle

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.

Tags: lifecycle

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, and any required verification guards have passed or been explicitly waived.
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

Tags: lifecycle

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. rejected — The decision was considered and explicitly declined.
4. superseded — The decision has been replaced by another ADR.

Valid transitions:

• proposed → accepted (via accept command)
• proposed → rejected (via reject 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”)
• accepted → rejected (accepted decisions must be superseded, not retroactively rejected)
• rejected → any (rejected is terminal)
• 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

When an ADR is rejected:

• The ADR MUST remain available as historical record
• The superseded_by field MUST NOT be set

Tags: lifecycle

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

Tags: lifecycle

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”)
3. Every guard named in the work item’s verification.required_guards MUST pass or be explicitly waived with a reason
4. If project verification is enabled, every project-level default guard MUST also pass or be explicitly waived with a reason

The effective required verification guards are the union of the work item’s verification.required_guards and, only when project verification is enabled, the project’s configured default guards. Only guards covered by explicit waivers are removed from that set.

Rationale: Prevents marking work as complete without defined success criteria or executable completion proof.

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. Project verification MUST default to disabled when the project config does not opt into it.

Tags: lifecycle, validation

Since: v0.1.0

Changelog

v0.3.0 (2026-03-17)

Add executable verification gates to work completion

Added

• Added required verification guard gate conditions for work completion

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