Versioning

The full versioning policy is at spec/versioning.md.

Summary

HushSpec uses Semantic Versioning (SemVer 2.0.0). The specification version is independent of any engine or SDK version - a security engine at version 5.0 may implement HushSpec 0.1.0, and a CLI tool at version 0.3 may implement HushSpec 1.2.0. There is no coupling between specification version numbers and implementation version numbers.

The hushspec field in a document declares which version of the specification the document conforms to. Implementations declare which specification version(s) they support. These are separate concerns.

v0.x: Unstable

The current series. During the v0.x development series:

Breaking changes between minor versions are permitted. A document valid under 0.1.0 may be invalid under 0.2.0. Fields may be renamed, removed, or have their semantics changed.
Patch versions (0.1.0 to 0.1.1) are non-breaking. Patch releases contain only clarifications, errata corrections, and editorial improvements that do not change document validity or evaluation semantics.
Implementations should pin to a specific minor version and document which v0.x version(s) they support. Multi-version support is encouraged but not required.

The v0.x series exists to allow the specification to evolve rapidly based on implementation experience before committing to stability guarantees.

v1.0+: Stable

Upon reaching v1.0.0, HushSpec commits to backward compatibility within each major version:

Minor versions (1.1, 1.2, ...) are additive only. New optional fields, new rule blocks, and new extension points may be introduced. Existing valid documents remain valid and retain their semantics. No existing field may be removed or have its meaning changed.
Patch versions (1.0.1, 1.0.2, ...) contain clarifications and errata only.
Major versions (2.0) may introduce breaking changes. A new major version resets the compatibility contract. Documents valid under 1.x may require migration to conform to 2.0.

Implementations supporting v1.x MUST accept any valid v1.y document where y <= x (i.e., an implementation supporting 1.3 must accept documents declaring 1.0, 1.1, 1.2, or 1.3).

Extension Module Versioning

In HushSpec v0.1.0, extensions (posture, origins, detection) do not declare separate per-document version fields. The companion extension specifications ship with the same repository release as the core spec.

A HushSpec document declares only the core hushspec version.
Companion extension specs are versioned by repository release, not by per-document version fields.
A future major version MAY introduce explicit extension versioning if it becomes necessary for interoperability.

Extension versioning is currently deferred. If and when independent extension evolution is needed, it will follow the same SemVer contract as the core specification.

Current Version

HushSpec Core: v0.1.0 (Draft)

Extension modules: v0.1.0 (Draft)

Migration Between Versions

Since only v0.1.0 exists today, no migration tooling is needed yet. When v0.2.0 is published, a migration guide will document all breaking changes and the h2h CLI will provide automated migration commands where possible.

For future reference, the general migration path is:

Review the changelog for the target version to identify breaking changes
Run h2h validate --version 0.2.0 policy.yaml to check your documents against the new version
Update the hushspec field and fix any validation errors
Run the conformance fixtures for the target version to verify behavior

Changelog

Release history and changelogs are published on the GitHub Releases page. Each release includes:

Summary of specification changes (new fields, changed semantics, deprecations)
Updated JSON Schema files
Updated conformance fixtures
SDK compatibility notes