Classification Layers & Status Lifecycle

ELI5

A requirement walks through a turnstile in one direction: drafted, approved, built, verified. If a newer requirement replaces it, the old one steps off the conveyor into the deprecated bin. The classification — L1 through L4 — is the floor of the building it lives on; it never changes mid-life.

Technical Deep Dive

Classification (5 Layers, 6 Values)

The requirement_classification enum collapses six values onto five conceptual layers:

L2 and L4 each carry two sub-flavours so that a non-functional spec (L2-Performance) and a test-shaped requirement (L4-Verification) are distinguishable without a second column.

Status Lifecycle

The requirement_status enum encodes a directed lifecycle. The DB does not enforce transitions (any value can be written), but services/core.py and the MCP update_requirement tool gate forward motion.

stateDiagram-v2
  [*] --> draft
  draft --> candidate
  candidate --> approved
  approved --> active
  active --> implemented
  implemented --> verified
  verified --> [*]
  draft --> deprecated
  candidate --> deprecated
  approved --> deprecated
  active --> deprecated
  implemented --> deprecated
  verified --> deprecated

deprecated is reachable from any state — there is no enum value for “rejected” because rejected requirements are simply deleted via the soft-delete path.

Priority Is Orthogonal

requirement_priority (P0-critical … P3-low) is independent of status. A P0-critical requirement may sit in draft for review while a P3-low is already verified.

Key Terms

• Classification → which design layer the requirement lives on (L1–L4); set at creation, immutable.
• Status → where it is in the review/build/verify lifecycle.
• Deprecated → terminal “do not use” state; the row stays for audit/traceability.

Q&A

Q: Can a row jump from draft to implemented? A: Not via the MCP service path — core.py walks transitions in order. The DB itself permits it because no CHECK constraint guards the field; only the application layer enforces order.

Q: Why are L2-Functional and L2-Performance separate enum values? A: They share a layer for traceability matrix rendering but distinguish functional from non-functional concerns at query time without a second column.

Q: What happens to relationships when a requirement is deprecated? A: They remain — deprecation is a status change, not a delete, so traceability matrices for historical reviews still resolve.

Examples

A new L4-Verification requirement starts at draft. After review it becomes candidate, then approved once stakeholders sign off. Once the test exists in CI it moves to implemented; once a green run is observed it becomes verified. If the requirement it verifies is itself deprecated, this row also moves to deprecated.