Release integrity

The npm package, MCPB archive, OCI image, source constant, lockfile root, MCP Registry manifest, versioned icon URL, generated config schema, and release tag are checked as one identity. The MCPB Registry package names the exact immutable GitHub Release URL and SHA-256, prompts only for the bot-token secret and one non-secret config file, and declares stdio transport. The npm package passes only the config selector; the OCI entry additionally fixes the operational command and hardened read-only mount. The same metadata gate scans every tracked and unignored repository file as raw bytes to prevent model- or harness-specific branding, including hidden binary metadata. Production and development dependencies are exactly pinned to the public npm registry, both container stages use one reviewed base-image digest, and the build engine, architecture emulator, and SBOM generator used by automation are pinned by image digest. Dependency installation disables lifecycle scripts and explicitly rebuilds only the reviewed esbuild version. CI also audits known vulnerabilities and npm registry signatures.

Release candidates are reconstructed from the selected tag. The npm archive and MCPB are each built repeatedly and verified in isolated consumers; the bundle additionally executes from a fresh unpacked directory. The archive, bundle, catalog evidence, and matching SPDX statements receive GitHub artifact attestations. Because npm does not permit staging or trusted publishing before a package exists, the first version is published from the exact attested archive by a maintainer completing an interactive passkey challenge. Every later npm release uses stage-only trusted publishing, followed by human two-factor approval. A separately approved image operation publishes only an absent exact semantic-version tag for both supported architectures, binds per-platform BuildKit provenance and SPDX records into the image index, signs provenance for that exact root digest, and verifies the public digest plus restricted runtime. Existing image tags are never overwritten.

After npm and OCI identities agree, an immutable GitHub Release operation reconstructs and attests the evidence under read-only authority, then delegates only draft creation and publication to a dependent protected job with contents: write plus read-only current-run artifact and attestation access. Its protected environment reviewer confirms repository-level Release immutability because GitHub does not expose that administrative setting to GITHUB_TOKEN; automation receives no standing repository-administration credential. The job installs a SHA-256-pinned GitHub CLI, requires the exact protected tag and source commit, generates deterministic notes and checksums, and allows only the npm archive, MCPB, credential-free catalog evidence, canonical release notes, validated SPDX SBOM, and SHA256SUMS. Because GitHub permits displayed immutable-Release notes to be edited, the canonical notes are an attested, checksummed asset. The job verifies the complete draft before publication, then requires GitHub's immutable Release attestation, verifies every local asset against it, and compares every public download byte-for-byte. Only after that exact immutable asset frontier exists may the Registry operation publish metadata containing the bundle's public URL and SHA-256. An exact immutable Release or Registry record is a no-op; published mutable state, prereleases, mismatched evidence, or unexpected assets fail closed, and automation never deletes or overwrites public evidence.

To verify a downloaded release archive:

npm pack guildcontrol@0.1.2
gh attestation verify guildcontrol-0.1.2.tgz \
  --repo j-256/guildcontrol \
  --signer-workflow j-256/guildcontrol/.github/workflows/release.yml \
  --source-ref refs/tags/v0.1.2 \
  --deny-self-hosted-runners
gh attestation verify guildcontrol-0.1.2.tgz \
  --repo j-256/guildcontrol \
  --signer-workflow j-256/guildcontrol/.github/workflows/release.yml \
  --source-ref refs/tags/v0.1.2 \
  --deny-self-hosted-runners \
  --predicate-type https://spdx.dev/Document/v2.3
gh release download v0.1.2 --repo j-256/guildcontrol --pattern guildcontrol-0.1.2.mcpb
gh release verify-asset v0.1.2 guildcontrol-0.1.2.mcpb --repo j-256/guildcontrol
docker pull ghcr.io/j-256/guildcontrol:0.1.2
gh attestation verify oci://ghcr.io/j-256/guildcontrol:0.1.2 \
  --repo j-256/guildcontrol \
  --signer-workflow j-256/guildcontrol/.github/workflows/release.yml \
  --source-ref refs/tags/v0.1.2 \
  --deny-self-hosted-runners \
  --bundle-from-oci

The release runbook covers the one-time attested first publication, protected npm staging, human approval, immutable OCI publication, immutable GitHub Release publication, registry registration, and independent verification.

Canonical source: docs/reference.md