ci: attest build provenance on tagged releases

Adds an actions/attest-build-provenance step to the package job that
fires on refs/tags/v* pushes. The attestation lets consumers verify the
shipped wheel/sdist came from this repo's CI before installing
(gh attestation verify ...). PR and main-branch builds remain
un-attested to keep the project's attestation feed scoped to actual
releases. The README's new Releases section documents the verification
command.

Author: Brad Kinnard

.github/workflows/ci.yml

@@ -49,6 +49,13 @@ jobs:
 
   package:
     runs-on: ubuntu-latest
+    # Attestation steps below need to issue an OIDC token and write the
+    # attestation; both default to off in the workflow-level permissions
+    # block. Job-scoped overrides keep the rest of the workflow read-only.
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
     steps:
       - uses: actions/checkout@v4
 
@@ -67,3 +74,14 @@ jobs:
         run: |
           pip install dist/skillcheck-*.whl
           skillcheck --version
+
+      - name: Attest build provenance
+        # Only attest tagged releases. Attestations on every CI run would
+        # flood the project's attestation feed and are not signed against
+        # an intended release artifact.
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: actions/attest-build-provenance@v1
+        with:
+          subject-path: |
+            dist/skillcheck-*.whl
+            dist/skillcheck-*.tar.gz

CHANGELOG.md

@@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Build provenance attestations on tagged releases. The CI `package` job now invokes `actions/attest-build-provenance@v1` against the built wheel and sdist when the ref starts with `refs/tags/v`. Consumers can verify with `gh attestation verify dist/skillcheck-*.whl --owner moonrunnerkc` before installing. Documented in the README's new `## Releases` section.
 - `.github/workflows/release-notes.yml`: when a GitHub Release is published, the workflow inspects `CHANGELOG.md`'s `[Unreleased]` block and, if it has un-promoted content for the tag, opens a PR against `main` that moves the block under a `[<tag>] - <today>` heading. No-op when `[Unreleased]` is empty or when the developer already promoted by hand.
 - `tests/test_agent_prompts_smoke.py`: snapshot tests that pin SHA-256 digests of each rendered prompt (six combinations: critique/graph x claude/codex/cursor) against `tests/fixtures/valid_basic.md`. Catches accidental edits to prompt scaffolding without requiring an oracle for prompt quality.
 - Published JSON Schema (Draft 2020-12) files for the agent IO contracts: `src/skillcheck/schemas/critique-v1.json` and `src/skillcheck/schemas/graph-v1.json`. Both ship with the wheel. `skillcheck.agents.SCHEMAS` maps `"critique-v1"` and `"graph-v1"` to the on-disk paths so callers can validate agent responses before invoking `--ingest-critique` or `--ingest-graph`. The schemas mirror the parser-enforced required fields, severity enum, kind enums, and score ranges; `test_published_schemas.py` guards drift between the schema files and the parsers.

README.md

@@ -115,6 +115,16 @@ Defaults live in a `skillcheck.toml` discovered upward from the validated path.
 - [`docs/case-study-silent-skill-failure.md`](docs/case-study-silent-skill-failure.md): VS Code dirname-mismatch incident.
 - [`skills/skillcheck/SKILL.md`](skills/skillcheck/SKILL.md): a SKILL.md that passes every rule.
 
+## Releases
+
+Tagged releases (`v*`) carry a SLSA build provenance attestation issued by `actions/attest-build-provenance@v1`. To verify a release artifact before installing:
+
+```bash
+gh attestation verify dist/skillcheck-*.whl --owner moonrunnerkc
+```
+
+This confirms the wheel was built by `moonrunnerkc/skillcheck` CI from the source at the tagged commit. Untagged builds (PR and main-branch CI) are not attested.
+
 ## License
 
 MIT. See [`LICENSE`](LICENSE).