docs(release): SBOM + Cosign signing, CHANGELOG.md, mermaid diagrams#74
Merged
Merged
Conversation
Three coupled changes to align release artifacts with what the docs claim: **Supply-chain hardening (matches the SECURITY.md claim).** - `.goreleaser.yaml`: adds `sboms:` (CycloneDX per archive via syft) and `signs:` (Cosign keyless via the runner's ambient OIDC identity, signs `checksums.txt`). The next tagged release ships `*.sbom.cdx.json` plus `checksums.txt.sig` + `checksums.txt.pem`. - `.github/workflows/release.yml`: adds `id-token: write` permission and installs syft + cosign before goreleaser runs. - `SECURITY.md`: until the next tagged release lands with these artifacts, the "Releases are signed Cosign-keyless and ship with a CycloneDX SBOM" line was an overclaim. Replaced with an honest "on the immediate roadmap" wording; the previous text returns automatically from the next release forward. **CHANGELOG.md (Keep-a-Changelog).** Maintained in-tree, complementing the goreleaser-generated commit-level release notes. Initial sections reconstructed for v1.0.0-beta.1 → v1.0.0-rc.1 from git log + PR titles. `[Unreleased]` carries the SBOM + Cosign + diagram entries from this PR. **Mermaid diagrams in the README.** - `Why Saga` → sequence diagram of the prompt lifecycle (You → Claude Code → hook → SQLite/markdown → AI → topic_write → next session). Annotated with the exact source files so readers can follow the call path in code. - `Architecture` → flowchart of the storage / runtime / agent surfaces with the transports labelled (MCP stdio, UserPromptSubmit, FTS5 + BM25 + relations). Reinforces "markdown is the source of truth, SQLite is regenerable cache". GitHub renders mermaid natively — no extra build step. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three coupled changes to align release artifacts with what the docs claim, plus the README diagrams you asked for.
Supply-chain hardening
SECURITY.md (introduced in #72) claimed "Releases are signed Cosign-keyless and ship with a CycloneDX SBOM" — but the goreleaser config produced neither. This PR makes the claim true from the next tagged release forward:
.goreleaser.yaml— addssboms:(one CycloneDX JSON per archive via syft) andsigns:(Cosign keyless onchecksums.txt, plus the Fulcio certificate alongside the signature). Verification recipe documented inline..github/workflows/release.yml—id-token: writepermission (required for OIDC keyless), plusanchore/sbom-action/download-syft@v0andsigstore/cosign-installer@v3steps before goreleaser runs.SECURITY.md— until the next tag lands with the artifacts, the claim was an overclaim. Rewritten to "on the immediate roadmap"; the original wording returns automatically from the next release forward.CHANGELOG.md (Keep-a-Changelog)
Maintained in-tree alongside the auto-generated goreleaser release notes. Sections for
[Unreleased],v1.0.0-rc.1,v1.0.0-beta.3,v1.0.0-beta.2,v1.0.0-beta.1reconstructed from git log + PR titles.Mermaid diagrams in the README
saga hook→ SQLite + markdown → AI →topic_write→ next session. Annotated with the source files so readers can follow it in code.GitHub renders mermaid natively — no build step, no images to maintain.
Re-tag plan after merge
v1.0.0-rc.1already shipped without the SBOM / signature artifacts. After merge, a follow-upv1.0.0-rc.2tag re-fires goreleaser with the new config so the SECURITY.md claim is true on a downloadable release.Test plan