Capability Lifecyclecapability

Lifecycle state machine for Capability nodes (e.g., 'L2 helpdesk operations', 'AP invoice processing', 'GST filing'; Scope v2 §0.1, §0.3). Forward path is the standard transition-execution sequence: Identified -> Designed -> Built -> InDualRun -> Cutover -> InService. A single backward edge (Designed -> Identified) permits a rethink before any build work has been committed. All forward transitions are gated to decision_maker; the backward edge is also decision_maker.

Node type

Capability

Initial state

Identified

Terminal states

InService

Full machine

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gcc.bootminds.com/ontology/state-machines/capability.json",
  "title": "Capability Lifecycle",
  "description": "Lifecycle state machine for Capability nodes (e.g., 'L2 helpdesk operations', 'AP invoice processing', 'GST filing'; Scope v2 §0.1, §0.3). Forward path is the standard transition-execution sequence: Identified -> Designed -> Built -> InDualRun -> Cutover -> InService. A single backward edge (Designed -> Identified) permits a rethink before any build work has been committed. All forward transitions are gated to decision_maker; the backward edge is also decision_maker.",
  "node_type": "Capability",
  "initial_state": "Identified",
  "terminal_states": [
    "InService"
  ],
  "states": {
    "Identified": {
      "description": "Capability has been named and scoped within a function/workstream. No formal design yet."
    },
    "Designed": {
      "description": "Target operating design has been documented (process, roles, system support, controls). Awaiting build/transition decisions."
    },
    "Built": {
      "description": "Capability is implemented in the target environment but not yet running operationally alongside the legacy / current source-of-truth. Ready to enter dual-run."
    },
    "InDualRun": {
      "description": "Capability is operating in parallel with the legacy source-of-truth for verification. Success criteria are being measured against the dual-run plan (Scope v2 §2.3.3)."
    },
    "Cutover": {
      "description": "Dual-run success criteria met and cutover executed. Legacy source-of-truth is decommissioned or quiesced. Capability is the system-of-record but stability is being observed."
    },
    "InService": {
      "description": "Capability is in steady-state operation. Terminal: no further transitions in normal flow. Future improvements happen via new Capability nodes or operational change requests outside this lifecycle."
    }
  },
  "transitions": [
    {
      "from": "Identified",
      "to": "Designed",
      "trigger_event": "CapabilityDesigned",
      "requires_role": "decision_maker",
      "requires_events": [],
      "guard_description": "The capability's decision_maker (typically a workstream lead) commits to a target design. Implementations SHOULD require a non-empty design document or design Decision linked to the Capability before this transition fires; that requirement lives in pack/UI validation, not in the lifecycle guard."
    },
    {
      "from": "Designed",
      "to": "Identified",
      "trigger_event": "CapabilityRethink",
      "requires_role": "decision_maker",
      "requires_events": [],
      "guard_description": "Back-edge: the decision_maker rescopes the capability before any build commitment. Only permitted from Designed (no rethink path from Built or later). Captured as a distinct event type so timeline reconstruction can distinguish a clean design pivot from a forward step."
    },
    {
      "from": "Designed",
      "to": "Built",
      "trigger_event": "CapabilityBuilt",
      "requires_role": "decision_maker",
      "requires_events": [],
      "guard_description": "Build is complete in the target environment. The decision_maker records the build-complete state, which makes the capability eligible for dual-run scheduling."
    },
    {
      "from": "Built",
      "to": "InDualRun",
      "trigger_event": "CapabilityInDualRun",
      "requires_role": "decision_maker",
      "requires_events": [],
      "guard_description": "Capability enters dual-run alongside the legacy source-of-truth. Wave assignment (Scope v2 §0.1 Transition Wave) and dual-run success criteria MUST be defined; their enforcement is at the pack/UI layer, not in this guard."
    },
    {
      "from": "InDualRun",
      "to": "Cutover",
      "trigger_event": "CapabilityCutover",
      "requires_role": "decision_maker",
      "requires_events": [],
      "guard_description": "Dual-run success criteria have been met; the decision_maker authorises cutover. Linked Gate (Scope v2 §1B.1) is typically the formal authority for this transition; the Gate's exit-criteria-checklist completion is the upstream gating mechanism but is enforced at the gate workflow layer, not duplicated here."
    },
    {
      "from": "Cutover",
      "to": "InService",
      "trigger_event": "CapabilityInService",
      "requires_role": "decision_maker",
      "requires_events": [],
      "guard_description": "Post-cutover stability is confirmed; the capability is declared in steady-state operation. The decision_maker records this transition; downstream maturity scoring (Scope v2 §1B.4) begins on the InService state."
    }
  ],
  "x-new-event-types-proposed": [
    {
      "event_type": "CapabilityDesigned",
      "purpose": "Forward transition Identified -> Designed.",
      "payload_sketch": "{ design_doc_ref?: string, target_op_model_ref?: string }"
    },
    {
      "event_type": "CapabilityRethink",
      "purpose": "Back-edge Designed -> Identified.",
      "payload_sketch": "{ rethink_reason: string }"
    },
    {
      "event_type": "CapabilityBuilt",
      "purpose": "Forward transition Designed -> Built.",
      "payload_sketch": "{ build_ref?: string }"
    },
    {
      "event_type": "CapabilityInDualRun",
      "purpose": "Forward transition Built -> InDualRun.",
      "payload_sketch": "{ wave_id: string, dual_run_plan_ref?: string }"
    },
    {
      "event_type": "CapabilityCutover",
      "purpose": "Forward transition InDualRun -> Cutover.",
      "payload_sketch": "{ gate_id?: string, cutover_at: string }"
    },
    {
      "event_type": "CapabilityInService",
      "purpose": "Forward transition Cutover -> InService.",
      "payload_sketch": "{ in_service_at: string }"
    }
  ],
  "x-decisions-surfaced": [
    "All six event types above (CapabilityDesigned, CapabilityRethink, CapabilityBuilt, CapabilityInDualRun, CapabilityCutover, CapabilityInService) are proposed by this state machine and MUST be added to event-types.json by the agent authoring that file in parallel. They follow the naming convention {NodeType}{StateOrAction} consistent with DecisionLocked / MilestoneAchieved / QuestionAnswered.",
    "Only one back-edge (Designed -> Identified) is permitted. Rationale: rethinks are cheap before build; after Built, scope changes cost real money and run through new Decisions / new Capabilities rather than state regression. Forward-only invariance after the Designed state makes audit and Programme Confidence simpler.",
    "The InDualRun -> Cutover transition does NOT require_events here, but the corresponding Gate workflow (Build Plan §7.1.5) is typically the operational gating mechanism. This state machine deliberately does not encode 'requires a successful Gate approval' as a same-transaction event constraint because gate approval is a multi-step process of its own; the Gate's outcome is materialised in the act of the decision_maker firing CapabilityCutover."
  ]
}