W
Wrkr

Release Integrity

Release Integrity

Release checks

  • Deterministic test gates in release workflow.
  • Contract and scenario validation before artifact generation.
  • Node24-ready action refs on the release path for all remediable workflow helpers, enforced by make lint-fast.
  • Public docs-site Markdown is treated as untrusted input; raw HTML, unsafe attributes, and unsafe link schemes are escaped or blocked before static HTML publish.
  • Docs-site production dependency advisories are release-trust inputs. High and critical advisories fail closed, and moderate advisories require an exact checked-in exception when no patched stable upstream dependency is available.
  • Tag releases build candidate artifacts without publishing them, verify checksums, generate an SBOM, run Grype, sign the checksum manifest, generate and verify provenance attestations, and only then publish GitHub release assets and Homebrew tap updates.
  • Exact release scanner/signing versions are pinned in CI and checked by local/CI hygiene gates.
  • CHANGELOG.md release-note entries finalized before tag publication with scripts/finalize_release_changelog.py, and tag builds verify them with scripts/validate_release_changelog.py.
  • Current bounded release-path exceptions are explicit and reviewed during every runtime uplift:
    • Homebrew/actions/setup-homebrew@cced187498280712e078aaba62dc13a3e9cd80bf
    • anchore/sbom-action@v0
    • anchore/scan-action@v4

Command anchors

make lint-fast
python3 scripts/validate_docs_site_audit.py --repo-root . --json
python3 scripts/resolve_release_version.py --json
python3 scripts/finalize_release_changelog.py --json
python3 scripts/validate_release_changelog.py --release-version vX.Y.Z --json
go test ./... -count=1
make test-contracts
scripts/validate_contracts.sh
make test-release-smoke

Docs-site trust posture

make docs-site-check and npm test -- --test-name-pattern markdown verify that hostile Markdown fixtures cannot publish raw script, unsafe attributes, malicious titles, or unsafe link schemes while safe docs features like repo-relative links, headings, code blocks, and Mermaid diagrams still render deterministically.

make docs-site-audit-prod is the single audit entry point for docs-site production dependencies. It runs npm audit --omit=dev --json through scripts/validate_docs_site_audit.py, then compares live advisory output against docs-site/security-advisory-exceptions.json. Each exception must remain:

  • owner-scoped
  • expiring
  • pinned to the advisory id, affected node path, direct dependency, and locked current version
  • removable as soon as a patched stable upstream release clears the advisory

If an advisory disappears, the node path changes, the direct dependency version drifts, or the exception expires, the gate fails closed instead of silently approving the docs site.

Factory profile trust posture

python3 scripts/validate_profiles.py --repo-root . --profile wrkr --json validates that Wrkr's Factory profile still points at current standards docs, user-facing docs paths, and high-risk review surfaces. This keeps code-review and app-audit automation aligned with the real repository layout, including the MCP detector packages, instead of relying on stale review targets.

Workflow rerun evidence

After changing release or docs workflow refs, rerun the affected workflow class on the branch and confirm the previous Node20 deprecation warning is gone for the upgraded refs:

gh workflow run release.yml --ref <branch>
gh workflow run docs.yml --ref <branch>
gh run watch --repo Clyra-AI/wrkr <run-id>

If a release-path helper still lacks a published Node24-ready upstream release, treat it as a bounded exception, document it in the same PR, and do not widen that exception set silently.

Publish sequence

For tag builds, treat release publication as the final gated step:

  1. Build candidate artifacts into dist/ without publishing them.
  2. Verify checksums.
  3. Generate an SBOM.
  4. Run Grype against the staged artifacts.
  5. Sign the checksum manifest.
  6. Generate and verify provenance attestations.
  7. Publish GitHub release assets and Homebrew tap updates from the verified staged set.

Install-path UAT (release-candidate)

Run install-path UAT locally before cutting a release tag:

Treat README.md, this page, and docs/install/minimal-dependencies.md as the shared install and release-parity contract: Homebrew, pinned Go install, wrkr version --json verification, and optional secondary @latest convenience guidance.

# Full local gate set + source/release/homebrew-path checks
scripts/test_uat_local.sh

# Fast smoke lane used by release CI job
scripts/test_uat_local.sh --skip-global-gates

# Validate exact public install commands (brew + pinned go install) for a published tag
scripts/test_uat_local.sh --release-version v1.5.0 --brew-formula Clyra-AI/tap/wrkr

Changelog finalization

Before tagging a release, resolve the next version from ## [Unreleased], then finalize the changelog and validate that the prepared versioned section matches the intended tag:

python3 scripts/resolve_release_version.py --json
python3 scripts/finalize_release_changelog.py --json
python3 scripts/validate_release_changelog.py --release-version vX.Y.Z --json

The finalizer promotes releasable Unreleased entries into ## [vX.Y.Z] - YYYY-MM-DD, adds a hidden semver hint for CI validation, and resets Unreleased to the canonical empty template so the next release only considers new entries. Publish that changelog update through a short-lived release-prep PR before creating the tag; the tag workflow validates the changelog content from the tagged commit itself.

For the full changelog ownership model, planning/implementation handoff, and file/script reference, see docs/trust/changelog-and-release-versioning.md.

After any public install path, verify the installed CLI deterministically:

wrkr version --json

Operational note

Consumers should verify published release checksums and provenance metadata before promotion. Maintainers should treat changelog updates as release-gating documentation work, not an optional follow-up. When using wrkr verify --chain --json as a release/promotion gate, inspect chain.verification_mode and chain.authenticity_status in addition to exit code 0; chain_only/unavailable is an explicit structural-only result, not authenticated proof verification.

Q&A

Which checks should pass before trusting a Wrkr release?

Deterministic test gates, contract validation, Node24 runtime policy checks, and integrity outputs (checksums/provenance) should all pass before promotion.

How do I verify artifact integrity after download?

Validate published checksums and provenance metadata against the release artifact you intend to promote.

Do docs-site development dependency advisories affect Wrkr runtime guarantees?

Wrkr runtime guarantees are tied to the Go CLI contract surfaces. Docs-site advisories should still be tracked, and production/runtime audit gates should remain green.