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 behind one protected review, followed by human two-factor approval. A second protected review authorizes dependency-chained OCI, immutable GitHub Release, and MCP Registry jobs. The OCI job alone 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, the immutable GitHub Release job alone receives contents: write plus read-only current-run artifact and attestation access. The promotion 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 job receive the product-scoped DNS seed and publish app.lasers.guildcontrol/discord metadata containing the bundle's public URL and SHA-256. The Registry job has no package, attestation-signing, OIDC, or repository-write authority. 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.

A publisher defect embedded in an immutable release tag may be recovered only through a distinct protected vMAJOR.MINOR.PATCH-recovery.N audit tag on a green main commit. Recovery accepts one explicit failed run ID, validates that run's repository, workflow, event, source tag, source commit, terminal failure, and exact retained evidence artifact, then verifies every recovered artifact attestation against the original release workflow, tag, commit, and GitHub-hosted runner boundary. The job checks out the original stable tag for all product metadata and public-distribution proofs while retaining the recovery tag as the reviewed execution identity. It receives the same narrow write authority and performs the same draft, immutability, public-byte, checksum, and asset-attestation checks as ordinary publication. Recovery cannot move a stable tag, replace evidence, accept an expired or mismatched artifact, repair a mutable published Release, or convert local files into release evidence.

To verify a downloaded release archive:

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

The release runbook covers the one-time attested first publication, protected npm staging, human approval, the single reviewed promotion chain, product-scoped Registry DNS authentication, credential recovery and rotation, and independent verification.

Canonical source: docs/reference.md