feat: attested quality-gate seam wiring, release process, and Diátaxis docs (#463)

Author: zircote

.claude/documentation-review.local.md

@@ -0,0 +1,140 @@
+# Attested source release for zircote/.github.
+#
+# This repo preaches attested delivery, so its own releases are attested: a
+# deterministic source bundle, a SLSA build-provenance attestation signed by
+# THIS workflow's OIDC identity, and a fail-closed self-verify. Consumers keep
+# pinning reusable workflows/actions by 40-char SHA; tags + Releases give them a
+# human-readable changelog and a verifiable artifact per release.
+#
+# Cut a release:
+#   git tag v1.2.0 && git push origin v1.2.0
+# or run this workflow manually (workflow_dispatch) against an existing tag.
+# Verify a release artifact: see RELEASING.md.
+
+name: release
+
+on:
+  push:
+    tags:
+      # GitHub Actions tag filters are glob, not regex. These coarse globs match
+      # any vX.Y.Z[-pre]; the job's first step validates strict semver.
+      - 'v*.*.*'        # stable, e.g. v1.2.0
+      - 'v*.*.*-*'      # prerelease, e.g. v1.2.0-rc.1
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Existing semver tag to (re)release, e.g. v1.2.0'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Attested source release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write       # create the GitHub Release, read the tag
+      id-token: write       # OIDC for keyless Sigstore signing
+      attestations: write   # write the build-provenance attestation
+    steps:
+      - name: Resolve and validate tag
+        id: tag
+        env:
+          EVENT: ${{ github.event_name }}
+          REF_NAME: ${{ github.ref_name }}
+          DISPATCH_TAG: ${{ inputs.tag }}
+        run: |
+          if [ "$EVENT" = "workflow_dispatch" ]; then
+            TAG="$DISPATCH_TAG"
+          else
+            TAG="$REF_NAME"
+          fi
+          # Fail closed on anything that is not vMAJOR.MINOR.PATCH[-prerelease].
+          if ! printf '%s' "$TAG" | grep -qE '^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$'; then
+            echo "::error::Tag '$TAG' is not semver (expected vX.Y.Z or vX.Y.Z-pre)"
+            exit 1
+          fi
+          PRERELEASE=false
+          case "$TAG" in *-*) PRERELEASE=true ;; esac
+          {
+            echo "tag=$TAG"
+            echo "version=${TAG#v}"
+            echo "prerelease=$PRERELEASE"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Checkout at tag
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          ref: ${{ steps.tag.outputs.tag }}
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Build deterministic source bundle
+        id: bundle
+        env:
+          TAG: ${{ steps.tag.outputs.tag }}
+          VERSION: ${{ steps.tag.outputs.version }}
+        run: |
+          ARTIFACT="zircote-github-${VERSION}.tar.gz"
+          # git archive is reproducible: same tree -> identical bytes/digest.
+          git archive --format=tar.gz --prefix="zircote-github-${VERSION}/" \
+            -o "$ARTIFACT" "$TAG"
+          sha256sum "$ARTIFACT" | tee "$ARTIFACT.sha256"
+          echo "artifact=$ARTIFACT" >> "$GITHUB_OUTPUT"
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
+        with:
+          subject-path: ${{ steps.bundle.outputs.artifact }}
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          TAG: ${{ steps.tag.outputs.tag }}
+          ARTIFACT: ${{ steps.bundle.outputs.artifact }}
+          PRERELEASE: ${{ steps.tag.outputs.prerelease }}
+        run: |
+          PRE_FLAG=""
+          [ "$PRERELEASE" = "true" ] && PRE_FLAG="--prerelease"
+          # Idempotent: a re-dispatch against an existing tag refreshes the
+          # release assets instead of failing on an already-published release.
+          if gh release view "$TAG" --repo "$REPO" >/dev/null 2>&1; then
+            echo "Release $TAG already exists; refreshing assets."
+            gh release upload "$TAG" "$ARTIFACT" "$ARTIFACT.sha256" \
+              --repo "$REPO" --clobber
+          else
+            gh release create "$TAG" \
+              --repo "$REPO" \
+              --title "$TAG" \
+              --generate-notes \
+              --verify-tag \
+              $PRE_FLAG \
+              "$ARTIFACT" "$ARTIFACT.sha256"
+          fi
+
+      - name: Verify the attestation (fail-closed dogfood)
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          ARTIFACT: ${{ steps.bundle.outputs.artifact }}
+        run: |
+          SIGNER="${REPO}/.github/workflows/release.yml"
+          # Tolerate brief attestation-index propagation, but fail closed.
+          for attempt in 1 2 3 4 5; do
+            if gh attestation verify "$ARTIFACT" \
+                 --repo "$REPO" --signer-workflow "$SIGNER"; then
+              echo "Attestation verified on attempt $attempt."
+              exit 0
+            fi
+            echo "Not yet verifiable (attempt $attempt); retrying in 10s..."
+            sleep 10
+          done
+          echo "::error::Attestation did not verify — refusing to leave an unverified release."
+          exit 1

.github/workflows/release.yml

@@ -5,3 +5,6 @@
 
 # subcog tool-generated audit logs (anywhere in the tree)
 **/.subcog/
+
+# Local-only Claude config (kept on disk, never committed)
+.claude/**/*.local.*

.gitignore

@@ -297,6 +297,17 @@ Cross-repo MCP access uses a GitHub App. Required App permissions must match the
 - Keep commits atomic and focused
 - Reference issues in commit messages when applicable
 
+## Release Process
+
+This repo is released by its own **attested** workflow (`.github/workflows/release.yml`,
+tag-driven). Push a semver tag (`git tag v1.2.0 && git push origin v1.2.0`) to
+build a deterministic `git archive` source bundle, attest SLSA build provenance
+over it (signed by `release.yml`), publish a GitHub Release with auto-notes, and
+fail-closed self-verify. Conventional-commit bump: `fix:`→patch, `feat:`→minor,
+`feat!:`/`BREAKING CHANGE:`→major. Full how-to + the consumer verify command:
+`RELEASING.md`. (`reusable-release.yml` is the separate `workflow_call` reusable
+for consumer **app** repos and does not attest.)
+
 ## Language Standards (for Templates)
 
 | Language | Version | Package Manager | Linter/Formatter | Type Checker |

CLAUDE.md

@@ -0,0 +1,55 @@
+# Releasing zircote/.github
+
+This repo ships an **attested** release process: each release is a deterministic
+source bundle carrying a SLSA build-provenance attestation signed by the
+`release.yml` workflow's OIDC identity, plus a GitHub Release with
+auto-generated notes. It dogfoods the same attested-delivery doctrine this repo
+provides to consumers.
+
+> Consumers continue to pin reusable workflows and actions by full 40-char
+> commit SHA (Dependabot keeps them fresh). Tags and Releases add a
+> human-readable changelog and a verifiable artifact per version — they do not
+> change the SHA-pinning rule.
+
+## Cut a release
+
+Releases are **tag-driven**. From an up-to-date `main`:
+
+```bash
+git tag v1.2.0           # semver: vMAJOR.MINOR.PATCH (or vX.Y.Z-rc.1 for a prerelease)
+git push origin v1.2.0
+```
+
+The `release` workflow then:
+
+1. Validates the tag is semver (fails closed otherwise).
+2. Builds `zircote-github-<version>.tar.gz` with `git archive` (reproducible).
+3. Attests SLSA build provenance over the bundle (`actions/attest-build-provenance`).
+4. Creates the GitHub Release with auto-generated notes and attaches the bundle
+   plus its `.sha256`.
+5. Re-verifies the attestation fail-closed before finishing.
+
+To re-run against an existing tag, dispatch the workflow manually
+(**Actions → release → Run workflow**) and supply the tag. A re-dispatch is
+idempotent: if a Release already exists for the tag it refreshes the attached
+assets (bundle + `.sha256`) rather than failing; the auto-generated notes from
+the original run are kept.
+
+Version bump convention (Conventional Commits): `fix:` → patch, `feat:` → minor,
+`feat!:` / `BREAKING CHANGE:` → major.
+
+## Verify a release artifact
+
+Download the `.tar.gz` from the release, then — independently from a
+workstation:
+
+```bash
+gh attestation verify zircote-github-<version>.tar.gz \
+  --repo zircote/.github \
+  --signer-workflow zircote/.github/.github/workflows/release.yml
+```
+
+`--signer-workflow` is required: under SLSA L3 the Fulcio SAN is the signing
+workflow. Inspect the provenance predicate with `--format json | jq` to confirm
+the source commit and build inputs. A successful verify proves the bundle is
+authentic and unmodified since it was built from the tag.

RELEASING.md

@@ -19,6 +19,8 @@ documentation for four kinds of need:
 - [Your first attested release](tutorials/first-attested-release.md) — build,
   sign, attest, and verify a container image end to end using the centralized
   workflows.
+- [Wire your first attested quality gate](tutorials/first-attested-quality-gate.md)
+  — run a CodeQL SAST gate and verify its signed, digest-bound verdict.
 
 ## How-to guides
 
@@ -39,6 +41,9 @@ executable, fully self-contained onboarding protocol for any org or repo.
 
 - [Reusable workflows](reference/workflows.md) — every centralized
   attested-delivery workflow: inputs, outputs, secrets, permissions.
+- [Quality-gate workflows](reference/quality-gate-workflows.md) — the SAST, SCA,
+  Trivy, Scorecard, VEX, k6, ZAP, seam, and verify-gates workflows: role, key
+  inputs, evidence, predicate type, signer.
 - [Attestation predicate definitions](reference/attestation-predicates/README.md)
   — the custom predicate types the quality gates sign: URI, body format, verdict
   rule, JSON Schema.
@@ -50,6 +55,9 @@ executable, fully self-contained onboarding protocol for any org or repo.
 - [Why attested delivery](explanation/attested-delivery.md) — the promotion
   invariant, the signing-isolation boundary, admission-time enforcement, and
   the change-record gate.
+- [Why attested quality gates](explanation/attested-quality-gates.md) — the
+  verdict-as-attestation model, signer pinning, custom predicate types, and the
+  "signed ≠ passed" caveat.
 
 ## Project plans
 
@@ -74,3 +82,5 @@ the Diátaxis quadrants:
 | `dora-emit.yml` | — | Yes | Yes | Yes |
 | `pin-check.yml` | — | Yes | Yes | — |
 | Admission enforcement (Kyverno / pre-deploy gate) | — | Yes | — | Yes |
+| Attested quality gates (SAST/SCA/Trivy/Scorecard/VEX/k6/ZAP) | Yes (SAST) | Yes | Yes | Yes |
+| Attestation seam (`reusable-attest-scan.yml`) | Yes | Yes | Yes | Yes |