Artifact Lifecycle

[!NOTE] Status: Planned. The lifecycle state machine describes the intended design. The CLI does not currently enforce state transitions — it validates schema structure only.

All artifacts (Products, Contracts, Workflows) will follow this lifecycle state machine. Transitions will be recorded in the Audit Trail.

State Machine

State Definitions

Transition Requirements

• draft → proposed: MUST pass schema validation. Run choochoo validate to check all artifacts against their schemas and quality rules.
• proposed → active: MUST have required approvals per policy. The number of approvers depends on the risk score — low-risk changes may be auto-approved, while high-risk changes require multiple human reviewers.
• active → deprecated: MUST specify a deprecation date. Downstream consumers (visible in the Lineage Graph) are notified.
• Any → retired: MUST NOT have active consumers (unless force flag is used). The Lineage Graph is checked to verify no downstream Products or Workflows depend on the artifact.

Invalid state transitions (e.g., draft → active without going through proposed) produce error E009 (Invalid state transition). In CI/CD pipelines, this results in exit code 1 (VALIDATION_ERROR).

Lifecycle and Governance

The lifecycle integrates tightly with ChooChoo's governance features:

• Risk Scoring: Transitions that move artifacts to higher-visibility states (e.g., proposed → active) trigger the risk scoring algorithm. The resulting score determines the approval level required.
• Audit Trail: Every state transition is recorded as a Decision Trace, capturing the actor (human or agent), the reason for the transition, and any approval evidence.
• Compliance Tags: Artifacts containing fields with sensitive compliance tags (e.g., pii, hipaa) face stricter transition requirements — they may require additional approvers or executive sign-off per your approval policies.
• Agents: AI agents can initiate transitions, but agent-initiated transitions to active always require human approval regardless of the computed risk score, unless the agent has explicit override authorization in its System Card.

Lifecycle in Practice

Use the choochoo governance submit command to transition an artifact from draft to proposed:

# Submit an artifact for approval
choochoo governance submit products/customer-360.yaml

# Check the current state
choochoo product show customer-360

# Approve (if you have the approver role)
choochoo governance approve <submission-id>

In The Station, lifecycle transitions are visualized in the Lineage Graph, and pending approvals appear in the governance dashboard. Users with the approver RBAC role can approve or reject transitions directly from the UI.

Configuration

You can configure lifecycle-related behavior in your .choochoorc configuration:

• validation.strict: When true, warnings about upcoming deprecations are treated as errors.
• governance.requireApproval: Compliance tags that always require human approval for state transitions.

See the Configuration guide for the full schema and available options.

Related