docs(release): explain package provenance

[Mr-Neutr0n]

Summary

• document the relationship between the npm package tag, bundled plugin manifest, and Codex runtime dependencies
• use the Git tree object as the immutable bundled-content identifier
• explain how to verify package gitHead and integrity metadata, and why external catalog versions must come from runtime release metadata

Fixes #234.

Verification

• verified the tag, commit, tree, package, and manifest commands against the current checkout
• pnpm run format passes
• model generation, diff, secret, burst, title, and repository-preflight checks pass

[mldangelo-oai]

Thanks for addressing #234. The tag-to-commit-to-bundled-tree mapping is useful, and the published 0.1.5 bundle matches its tagged source. Before merging, please distinguish signed provenance verification from registry metadata inspection and document the supported historical releases that do not expose gitHead.

[mldangelo-oai]

npm view only reports registry metadata; it does not verify the package bytes or a signed provenance attestation. gitHead is package metadata and dist.integrity is a tarball digest, so this recipe does not establish that the npm artifact was produced from the tagged commit and bundled tree. The release workflow additionally checks the archive and runs npm audit signatures --include-attestations, then binds the attestation to the expected repository, commit, and release run. Please document comparable verification, or explicitly describe this command as metadata inspection rather than provenance verification.

[mldangelo-oai]

This is not true for every published release: 0.1.0 and 0.1.1 both omit gitHead from their published package manifests. I checked the release archives; 0.1.5 does contain the expected commit. verifyGitHubPublishedRelease explicitly permits those two historical versions only after recovering the commit from verified signed provenance. Please qualify gitHead as available starting with 0.1.2 and document the attestation-based fallback for 0.1.0 and 0.1.1.

[Mr-Neutr0n]

Addressed the review: clarified that npm registry metadata is inspection-only, documented signed SLSA verification with npm audit signatures, and named 0.1.0/0.1.1 as the only legacy releases that may omit gitHead. Mr-Neutr0n@29e0bed