DIDP v2

DIDP v2 extends DIDP v1 with semantic versioning enforcement. All v1 rules remain in effect unless explicitly modified below.

Changes from v1

Added: Versioning Block

The iteration_state.yaml schema gains an optional versioning: block for tracking semantic version intent.

Added: Workflow Contract Versioning Policy

The workflow contract gains a versioning policy section.

Versioning Block (New in v2)

Schema Addition

Add to iteration_state.yaml:

versioning:
  scheme: semver                    # REQUIRED: versioning scheme (semver)
  current: "1.2.3"                  # OPTIONAL: current version before iteration
  planned_bump: minor               # REQUIRED at spec_lock: major|minor|patch
  enforcement: required|recommended # OPTIONAL: default is recommended
  changelog_required: true          # OPTIONAL: require changelog entry

Field Definitions

Field	Type	Required	Description
`scheme`	string	Yes	Versioning scheme. MUST be `semver` in v2.
`current`	string	No	Current version before this iteration.
`planned_bump`	enum	At spec_lock	Version bump intent: `major`, `minor`, or `patch`.
`enforcement`	enum	No	`required` or `recommended`. Default: `recommended`.
`changelog_required`	boolean	No	Whether changelog entry is required. Default: `false`.

Phase Requirements

Phase	Versioning Requirement
planning	MAY declare `planned_bump`
analysis	SHOULD validate bump intent against scope
spec_lock	MUST declare `planned_bump` if `enforcement: required`
implementation	No change
testing	No change
archive	MUST include version tag if `enforcement: required`
merge	MUST validate version consistency
complete	Version recorded in iteration state

Bump Intent Rules

Bump	When Required
`major`	Breaking changes to protocols or public interfaces
`minor`	New features, backwards compatible
`patch`	Bug fixes, documentation corrections

Example

iteration:
  id: ITER-2025-12-26-B
  goal: "Add semantic versioning enforcement to DIDP"

versioning:
  scheme: semver
  current: "1.0.0"
  planned_bump: major
  enforcement: required
  changelog_required: true

phase:
  name: spec_lock
  # ... rest of iteration state

Workflow Contract Additions (v2)

Add the following section to the workflow contract:

Versioning Policy

SemVer is mandatory for protocol specifications.
Breaking changes require major bump — no exceptions.
All iterations SHOULD declare bump intent at spec_lock phase.
Changelog entries are required when changelog_required: true.

Version Source

Each project MUST have exactly one canonical version source:

VERSION file, or
package.json / pyproject.toml / equivalent, or
Git tag

The version source MUST be updated during the archive phase.

Enforcement Levels

Level	Behavior
`required`	Phase transitions blocked if versioning rules violated
`recommended`	Warnings emitted but transitions allowed

Backward Compatibility

DIDP v2 is backward compatible with v1:

The versioning: block is optional
All v1 iteration states remain valid
No v1 behavior is removed or modified
v2 adds capabilities without breaking existing workflows

Projects using v1 can adopt v2 incrementally by adding the versioning: block when ready.

Migration from v1

To upgrade from v1 to v2:

Add versioning: block to iteration_state.yaml
Update workflow contract with versioning policy section
Set enforcement: recommended initially
Upgrade to enforcement: required when ready

No other changes are required.

References

DIDP v1 — Base protocol (superseded by v2)
PPP v1 — Publication protocol
Semantic Versioning — SemVer guidance
ROADMAP — Version roadmap