Stability and Versioning
Schema Stability
| Schema | Version | Commitment |
|---|---|---|
| Observations | obs.v0.1 | Stable — no breaking changes within 1.x |
| Controls | ctrl.v1 | Stable — no breaking changes within 1.x |
| Output | out.v0.1 | Stable — no breaking changes within 1.x |
Schema versions are independent of the CLI version. The v0.1 designation indicates the initial stable schema. Breaking changes (if ever needed) would increment to v0.2 with a migration guide.
Observations and controls are validated at runtime against embedded JSON Schema Draft 2020-12 files (see schemas/). Output artifacts are also validated at runtime against embedded schemas (out.v0.1, diagnose.v1) before emission.
See controls/MIGRATION.md for migration guidance.
Exit Code Stability
Exit codes are part of the public API and will not change within a major version:
| Code | Meaning | Stable? |
|---|---|---|
| 0 | Success / no violations | Yes |
| 1 | Security-audit gating failure | Yes |
| 2 | Input or validation error | Yes |
| 3 | Violations detected | Yes |
| 4 | Internal error | Yes |
| 130 | Interrupted (SIGINT) | Yes |
Exit code 1 is not used for violations. Exit code 3 means violations.
CLI Flag Stability
Flags documented in the README and command help are stable. Undocumented flags may change without notice.
Output Format Stability
JSON output fields in run, summary, and findings are stable within a major version. New fields may be added (additive changes are not breaking). No fields will be removed or renamed within 1.x.
Pinned Dependencies
Stave pins all dependencies to exact versions. The source of truth is the Go module file (go.mod) and the project's version policy.
| Dependency | Version | Role |
|---|---|---|
| Go | 1.26.3 | Build toolchain |
| Cobra | v1.10.2 | CLI framework |
| pflag | v1.0.10 | Flag parsing |
| yaml.v3 | v3.0.1 | Control YAML parsing |
| golangci-lint | v2.8.0 | CI linting |
Dependency updates go through CI checks including govulncheck and license compliance (go-licenses check). Forbidden licenses (GPL, AGPL, SSPL, LGPL) fail the build.
Build Reproducibility
Release binaries are reproducible. Anyone with the matching Go version can rebuild from source and compare checksums:
CGO_ENABLED=0— pure Go, no C dependencies-trimpath— removes local filesystem paths-buildid=— removes build ID-ldflags "-s -w"— strips debug symbols
See Release Security for instructions.
Supported Platforms
| OS | Architecture |
|---|---|
| Linux | amd64, arm64 |
| macOS | amd64 (Intel), arm64 (Apple Silicon) |
| Windows | amd64 |
Deprecation Policy
Before removing a flag, command, or output field:
- The item is marked deprecated in help text for at least one minor release.
- A migration path is documented.
- The removal is noted in the changelog.
Documentation Versioning Policy
Documentation is versioned with source code in this repository.
- Docs updates for user-visible behavior changes must land in the same PR.
CHANGELOG.mdis the release-facing summary for docs and code changes.- CLI reference pages are generated from command definitions to reduce drift.
- Docs are validated by CI link checks.