Skip to main content

Validation contract

One command runs the complete local gate:

go run ./tools/validate

It runs with CGO_ENABLED=0 and GOPROXY=off.

Stages​

  1. gofmt drift check.
  2. go vet ./....
  3. Full unit, contract, and integration tests.
  4. Statement coverage of the merged profile (unit tests plus spawned binaries) with a 97.4 percent floor, compared at full precision.
  5. CGO-free builds for Linux, macOS, and Windows on amd64 and arm64.
  6. Standard-library-only dependency policy.
  7. Forbidden production import policy.
  8. Installer syntax, checksum flow, marketplace JSON, plugin license, and OpenCode plugin pin checks.
  9. PromptScript 1.19.1 strict validation and generated output drift check, including the bounded OpenCode plugin patch and instructions.
  10. Repository scans for credentials, unfinished markers, private paths, and forbidden dash characters.

The command fails on the first stage failure. Tests use temporary repositories and do not need credentials, network access, personal Git configuration, or untracked project files.

Narrow commands​

go test ./internal/engine
go test ./internal/provenance
go test ./internal/hooks
go vet ./...
CGO_ENABLED=0 go build ./...

Run package tests during development. Run the complete contract before every pull request.

CI checks​

Stable pull request check names:

Validate repository
Quality and build
Coverage
Dependency review
CodeQL
Validate PromptScript

Quality and build aggregates the operating system test matrix and verified GoReleaser snapshot. The snapshot must contain six archives, six SPDX JSON SBOM files, and a non-empty SHA256 checksum file.

Validate PromptScript compiles every build profile and target, applies the OpenCode plugin and subagent patch with go run ./tools/validate -patch-opencode, and fails on any difference from the committed files.

Nightly robustness repeats randomized attribution scenarios and fuzzes line splitting and hook payload parsing. Nightly checks are not branch requirements because they do not conclude on every pull request.

Coverage policy​

  • Total merged statement coverage must remain at least 97.4 percent. The merge combines the unit-test profile with profiles from binaries built with -cover, so statements only spawned binaries execute still count. The floor compares the exact merged percentage, not the rounded go tool cover -func output. The floor is calibrated against the Go 1.24 toolchain, which splits more coverage blocks than newer toolchains, and stays below the measured total because more than 200 statements are defensive-unreachable.
  • Codecov patch coverage target is 100 percent.
  • Project coverage may drop by at most 1 percent.
  • Parsing, path validation, storage recovery, hooks, and attribution invariants need direct review even when aggregate coverage passes.
  • Never lower a threshold only to pass a change.

Release validation​

Release changes also run:

goreleaser release --snapshot --clean

Inspect archive names, file allowlist, version output, checksums, and SBOMs. See RELEASES.md.