witnora

Witnora-only release governance v1

Witnora has one maintained npm implementation: packages/witnora-cli. agentcert@0.9.0 is a frozen compatibility facade and is never versioned or published again.

Operator path

Prepare the next stable version from a clean branch:

npm run release:prepare -- patch

patch may be replaced by minor, major, or an explicit stable version such as 1.0.0. The command updates only:

• packages/witnora-cli/package.json;
• packages/witnora-cli/package-lock.json.

Review, commit, and merge those files with the release changes. After main CI passes, push the matching tag:

git tag -a vX.Y.Z -m "Witnora vX.Y.Z"
git push origin vX.Y.Z

No npm token, legacy package update, handwritten GitHub Release, or manual artifact upload is part of the normal path.

Stable SemVer contract

Only vX.Y.Z tags are accepted. Pre-release identifiers and build metadata are rejected by v1 of this policy.

• patch: backward-compatible fixes and internal hardening;
• minor: backward-compatible commands, options, exports, or evidence fields;
• major: intentional breaking changes to CLI or public module contracts.

Stable agentcert.* evidence schema identifiers have their own explicit schema versioning policy. Changing an npm major version does not silently rewrite an evidence schema.

The tag, canonical package, lockfile root, and repository metadata must agree. The policy also verifies that the legacy package remains exactly agentcert@0.9.0 -> witnora@0.9.0.

Automated release chain

.github/workflows/publish-witnora-npm.yml performs the following sequence:

1. verifies the release policy and exact tag;
2. requires a new version to be greater than npm’s highest stable version;
3. installs the lockfile without a release cache;
4. builds, tests, and audits production dependencies;
5. packs one canonical npm tarball;
6. generates an SPDX 2.3 SBOM;
7. runs clean-install and upgrade compatibility scenarios;
8. writes a release manifest and a governed mutation from the previous npm version to the candidate;
9. issues a one-hour, single-use promotion grant with no capability expansion;
10. creates GitHub attestations for the tarball, SBOM, mutation, and grant;
11. publishes that same tarball through npm Trusted Publishing;
12. independently downloads the registry tarball and issues an attested promotion receipt only when the bytes match;
13. writes final SHA-256 checksums for every release artifact;
14. calls the public external Node 20/22/24 canary;
15. creates the GitHub Release only after the external canary passes.

The workflow is retry-safe. If npm already contains the version, the registry tarball must match the locally reconstructed tarball before the workflow can continue. npm versions remain immutable; a bad release is corrected by a new patch release, never by replacing bytes.

Release evidence

Every successful GitHub Release contains:

• witnora-X.Y.Z.tgz;
• witnora-X.Y.Z.spdx.json;
• witnora-X.Y.Z.compatibility.json;
• witnora-X.Y.Z.release-manifest.json;
• witnora-X.Y.Z.agent-mutation.json;
• witnora-X.Y.Z.promotion-grant.json;
• witnora-X.Y.Z.promotion-receipt.json;
• SHA256SUMS.

The tarball has two GitHub attestations: build provenance and an attached SPDX SBOM. npm Trusted Publishing separately publishes npm provenance linking the registry package to the source repository and workflow identity. The mutation, grant, and receipt each have a separate GitHub OIDC artifact attestation. A successful receipt leaves continuous assurance at REVALIDATION_REQUIRED; the public canary and successor review are separate evidence, not an implicit promotion to CURRENT.

Consumers can verify downloaded release bytes with:

sha256sum --check SHA256SUMS
gh attestation verify witnora-X.Y.Z.tgz --repo Kakarottoooo/agentcert
gh attestation verify witnora-X.Y.Z.tgz \
  --repo Kakarottoooo/agentcert \
  --predicate-type https://spdx.dev/Document/v2.3

Provenance proves where and how the package was built. It does not prove that the package is vulnerability-free or that an evaluated agent is safe.

Local checks

npm run release:verify
npm run release:governance:test
npm run release:package-smoke
npm run release:public-canary -- --version latest

The public canary is intentionally outside the product repository at Kakarottoooo/witnora-install-smoke. It runs daily and is also called as a required reusable workflow during each release.

Recovery

• Tag mismatch: delete the unpushed local tag, prepare the correct package version, and tag again.
• Failure before npm publish: fix the source and move the tag only if it has not been published or consumed.
• Failure after npm publish: do not move or reuse the tag; prepare a patch release.
• External canary failure: no GitHub Release is created. Diagnose the public install path, then rerun the immutable tag workflow after the fix is released under a new version where necessary.

This site is open source. Improve this page.