Spec 14: Lifecycle & Versioning

DWS Spec 14: Lifecycle & Versioning

Digital Worker Standard — DWS Specification

Version: 1.0 Tier: 4 — Governance Status: Release Candidate Dependencies: Spec 0 (Project Structure), Spec 1 (Worker Identity), Spec 2 (Knowledge Schema)

1. Overview

This specification formalises the lifecycle of a digital worker from creation through retirement. Every human employee has a lifecycle: hired, onboarded, probation, active employment, performance review, promotion, departure. Digital workers are no different.

Lifecycle management matters for three reasons:

Safety. A worker in testing should not receive production intents.
Accountability. A worker in production has an auditable history of how it got there.
Marketplace. When you acquire a worker from the marketplace, its lifecycle stage and version history tell you what you’re getting.

2. Lifecycle Stages

Stage	Description	Can Receive Intents?	Knowledge Persists?
`draft`	Initial definition. Under active authoring.	No	No
`testing`	Running against test intents in a sandboxed environment.	Test intents only	Session-scoped only
`staging`	Running against production-like intents with human oversight.	Staging intents only	Yes, tagged as staging
`production`	Live, receiving and executing real work.	Yes	Yes
`deprecated`	Still operational but scheduled for replacement. New deployments should use the replacement.	Yes (with warnings)	Yes
`retired`	No longer executes. Knowledge and event history preserved for audit.	No	Archived, read-only

2.1 Stage Transitions

draft -> testing -> staging -> production -> deprecated -> retired
                                    |                        ^
                                    +--- (hotfix) -----------+

Transition	Triggered By	Requirements
draft -> testing	Worker author	`dws validate` passes. All required fields present.
testing -> staging	Worker author or CI	Minimum test run count met. Verification pass rate above threshold.
staging -> production	Human approver	Staging period completed. Approval gate passed.
production -> deprecated	Worker author	Replacement worker specified. Migration guide provided.
deprecated -> retired	Automated or human	Sunset date reached. All active intents reassigned.
production -> retired	Human (emergency)	Bypass deprecation for urgent removal. Requires explicit justification.

2.2 Promotion Criteria

Each transition MAY define promotion criteria that must be met:

{
  "lifecycle": {
    "stage": "testing",
    "promotion_criteria": {
      "testing_to_staging": {
        "min_test_runs": 50,
        "min_verification_pass_rate": 0.95,
        "min_test_duration": "P7D",
        "requires_human_approval": false
      },
      "staging_to_production": {
        "min_staging_runs": 20,
        "min_verification_pass_rate": 0.98,
        "min_staging_duration": "P14D",
        "requires_human_approval": true,
        "approver_role": "engineering-lead"
      }
    }
  }
}

Promotion criteria are RECOMMENDED but not REQUIRED. Organisations without formal promotion processes can transition stages manually.

3. Version History

3.1 Version Record

Every version of a worker descriptor is a git-tagged artifact. The version history provides a complete record of how the worker has evolved.

{
  "version_history": [
    {
      "version": "1.0.0",
      "released_at": "2026-03-01T00:00:00Z",
      "stage_at_release": "production",
      "changelog": "Initial production release.",
      "git_tag": "worker/contract-reviewer/v1.0.0"
    },
    {
      "version": "1.1.0",
      "released_at": "2026-04-01T00:00:00Z",
      "stage_at_release": "production",
      "changelog": "Added indemnification clause analysis skill.",
      "git_tag": "worker/contract-reviewer/v1.1.0"
    }
  ]
}

3.2 Employment Record

For marketplace workers, the version history is combined with execution metrics to form an employment record: a verifiable history of the worker’s performance across deployments.

Metric	Description
`total_runs`	Total number of intent executions.
`verification_pass_rate`	Proportion of runs that passed verification.
`average_execution_time`	Mean time to complete an intent.
`escalation_rate`	Proportion of runs that required escalation.
`knowledge_entries_accumulated`	Number of institutional knowledge entries created.
`active_since`	Date the worker first entered production.

This record is what distinguishes a marketplace worker from a template. A worker with 1,000 successful runs and a 98% verification pass rate is meaningfully different from a freshly created definition.

4. Upgrade and Migration

4.1 Major Version Upgrades

When a worker undergoes a major version upgrade (e.g., v1.x to v2.0):

The new version starts at testing stage regardless of the old version’s stage.
Knowledge transfer follows the rules in Spec 2, Section 5.5.
The old version transitions to deprecated with the new version as replacement.
Active intents are not automatically reassigned. The runtime continues to route to the old version until explicitly switched.

4.2 Minor Version Upgrades

Minor version upgrades (e.g., v1.0 to v1.1) may be promoted directly to the same stage as the current version, provided:

The upgrade is non-breaking (see Spec 1, Section 5.3).
The worker passes validation at the current stage.
The runtime supports hot-swapping (implementation-specific).

4.3 Rollback

Rollback is a git revert of the worker descriptor to a previous version tag. The rolled-back version inherits the lifecycle stage of the version it replaces. Knowledge entries created during the rolled-back version’s tenure are flagged for review but not automatically deleted.

5. Marketplace Lifecycle

Workers published to the marketplace carry their lifecycle metadata:

Field	Description
`published_version`	The version published to the marketplace.
`lifecycle_stage`	Must be `production` to publish.
`employment_record`	Aggregated performance metrics (Section 3.2).
`provenance`	Author, organisation, publication date (Spec 3, Section 2.1).
`knowledge_export`	Exportable knowledge entries (Spec 2, Section 5.4).

Workers in draft, testing, or staging MUST NOT be published to the marketplace. Workers in deprecated or retired MUST be flagged accordingly in marketplace listings.

6. References

Spec 0: Project Structure — Lifecycle stage declared in jobspec.json manifest.
Spec 1: Worker Identity — Versioning and deprecation protocol for worker descriptors.
Spec 2: Knowledge Schema — Knowledge transfer between worker versions. Knowledge export for marketplace.
Spec 12: Compliance & Governance — Lifecycle stage determines applicable compliance requirements.