ci(workflows): add CI, security, release, and supply-chain pipeline

[cjimti]

Closes #3. Part of #1 (project bootstrap, v0.1).

This is phase 2 of 7 in the v0.1 bootstrap. It lands the entire CI / security / release pipeline before any Go source exists, so subsequent phases (#4 through #8) merge with all gates already enforced. The workflows are designed to tolerate the empty source tree and to activate automatically once phase 3 (#4) introduces the first .go file.

Summary

• 8 GitHub Actions workflows wired to the events called for in spec §14.2 (PR, push to main, weekly cron, tag push, branch-protection rule, manual dispatch).
• Every third-party action SHA-pinned with the human-readable version as a trailing comment, per spec §14.10. SHAs were fetched live from the GitHub API immediately before writing this PR.
• GoReleaser configuration with five-arch cross-compile, Cosign keyless signing, dual-format SBOMs (CycloneDX + SPDX), conventional-commits changelog, and an optional Homebrew tap publish step that skips silently when the tap token is absent.
• Codecov configuration with the spec's core/ >80% gate, cmd//examples//docs//tests excluded.
• Operator runbook at docs/ci.md covering workflow inventory, secret matrix, action-pinning policy, release process with verification commands, branch-protection setup, and troubleshooting.

Phase mapping

Phase	Issue	Branch	Status
1. Repo skeleton & hygiene	#2	feat/bootstrap-skeleton	merged (#9)
2. CI & release pipeline (this PR)	#3	feat/bootstrap-ci	open
3. core/event + core/provider	#4	feat/bootstrap-event-provider	next
4. core/mcp + core/session	#5	feat/bootstrap-mcp-session
5. core/loop + core/router + core/approval	#6	feat/bootstrap-loop-router-approval
6. cmd/ask CLI	#7	feat/bootstrap-ask
7. examples/acme-revenue + ADR + architecture doc	#8	feat/bootstrap-acme-example

Workflow inventory

ci.yml

Pipeline: detect → (lint ‖ test ‖ build) → ci-pass.

• detect runs find . -name '*.go' -not -path './.*' -not -path '*/testdata/*' -print -quit and exposes a has-source output. Downstream jobs use if: needs.detect.outputs.has-source == 'true' to gate themselves until phase 3 lands.
• lint runs go mod verify, go mod tidy -diff (fails on drift), gofmt -l, go vet, golangci-lint config verify, golangci-lint run. The first three run unconditionally so config / module-graph regressions are caught immediately even with no source.
• test runs on ubuntu-latest and macos-latest with go test -race -shuffle=on -count=1 -covermode=atomic -coverprofile=coverage.out ./.... Coverage uploaded to Codecov from ubuntu-latest only with the core flag.
• build cross-compiles on ubuntu-latest across darwin/{amd64,arm64}, linux/{amd64,arm64}, windows/amd64 with CGO_ENABLED=0 and -trimpath.
• ci-pass is an aggregator that surfaces a single status check for branch protection. It tolerates skipped from test/build (empty-tree case) but not from lint.

security.yml

Four parallel scanners. All findings flow through SARIF into the GitHub security tab.

• gosec with -fmt sarif -no-fail, uploaded via github/codeql-action/upload-sarif.
• govulncheck invoked through go tool govulncheck ./...; runs even on the empty tree to validate the module graph.
• semgrep runs in the official Semgrep container pinned to a multi-arch manifest digest, with p/security-audit, p/secrets, p/golang, and p/owasp-top-ten rulesets. SARIF upload via the CodeQL action.
• trivy filesystem scan; exit-code: 0 so the SARIF gate (visible in the security tab) is the source of truth, not a forced PR failure.

codeql.yml

Go analysis with the security-extended and security-and-quality query packs. Init/autobuild/analyze gated behind the same detect step so the workflow is a no-op until source exists.

scorecard.yml

Weekly + push-to-main + branch_protection_rule triggers. Uses ${{ secrets.SCORECARD_READ_TOKEN || secrets.GITHUB_TOKEN }} so the workflow runs without the optional fine-grained PAT (Branch-Protection check returns ? until the PAT is added). Results published and uploaded as SARIF.

dependency-review.yml

PR-only. fail-on-severity: high, comment-summary-in-pr: on-failure, license allowlist mirroring spec §14.7 (Apache-2.0, MIT, BSD-2/3-Clause, ISC, MPL-2.0, Unlicense, CC0-1.0, Zlib, BSD-2-Clause-Patent).

pr-title.yml

Conventional Commits enforcement via amannn/action-semantic-pull-request. Allowed types: feat, fix, docs, chore, refactor, test, perf, ci, build, revert. Subject must start with an alphanumeric character.

fuzz.yml

Nightly cron at 04:00 UTC plus workflow_dispatch with a configurable duration input (default 5m). The detect job dynamically discovers Fuzz* targets via go test -list 'Fuzz.*' and emits a JSON matrix; the fuzz job fans out one runner per (package, FuzzXxx) pair. Failures upload testdata/fuzz/ as a workflow artifact for triage. No-op when no targets exist.

release.yml

Tag-driven (v*.*.*) with manual workflow_dispatch fallback. Single release job with the full provenance permission set (contents: write, packages: write, id-token: write, attestations: write).

Steps: harden-runner → checkout (fetch-depth: 0) → setup-go → install Cosign → install Syft → GoReleaser (~> v2, release --clean) → actions/attest-build-provenance over dist/*.{tar.gz,zip,sbom.*} → SBOM upload as workflow artifact.

The provenance step produces SLSA v1 in-toto attestations signed via Sigstore (keyless OIDC), verifiable with gh attestation verify.

.goreleaser.yaml

• homebrew_casks (post-brews-deprecation) with binaries: [ask] (post-binary-deprecation), pushing to plexara/homebrew-tap under Casks/. skip_upload: auto so an absent HOMEBREW_TAP_GITHUB_TOKEN doesn't fail the release.
• 5-arch cross-compile (darwin/{amd64,arm64}, linux/{amd64,arm64}, windows/amd64) with CGO_ENABLED=0, -trimpath, -s -w, and -X main.{version,commit,date,builtBy} ldflags.
• tar.gz archives (zip for Windows) carrying LICENSE, README.md, SECURITY.md.
• cosign sign-blob over the SHA-256 checksums file with --yes (CI-safe; OIDC issuer is token.actions.githubusercontent.com).
• Dual-format SBOMs per archive: CycloneDX + SPDX, both via Syft.
• Conventional Commits changelog with grouped sections (Features / Bug fixes / Performance / Documentation / Other) and noisy categories (chore(deps):, chore(ci):, test:, ci:, merge commits) filtered out.

.github/codecov.yml

• coverage.range: 70...95, precision: 2, round: down.
• core flag scoped to core/ paths only, gated at 80% target with 1pp threshold on both project and patch checks. if_ci_failed: error so a CI failure also fails the coverage check.
• cmd/, examples/, docs/, **/testdata/**, **/*_test.go, and **/mocks/** are ignored.
• Comment layout: reach,diff,flags,files,footer.

docs/ci.md

Single source of truth for operating the pipeline. Sections:

• Workflow inventory table (trigger × purpose).
• Secrets matrix with exact names, criticality, and how to obtain each PAT (fine-grained scoping for the optional ones).
• Action-pinning policy with example syntax and Dependabot's role.
• Coverage gate explanation tying the codecov.yml back to spec §14.3.
• Empty source-tree handling explanation.
• Release process: tag → workflow → artifact verification commands (cosign + gh attestation verify).
• Branch-protection setup checklist with the exact required-status-check names (ci pass, lint, analyze go, govulncheck, gosec, semgrep, trivy fs, review, conventional commit).
• Troubleshooting for the most common failure modes.

Hard requirements verified

• actionlint -color over all 8 workflows → exit 0
• goreleaser check → 1 configuration file(s) validated, no deprecations
• go tool golangci-lint config verify → exit 0
• All 10 YAML files parse cleanly via python3 -c yaml.safe_load
• 16 distinct third-party actions SHA-pinned with # vX.Y.Z trailing comments

Empty source-tree handling

Until phase 3 (#4) lands the first Go source file:

• ci-pass aggregator returns success.
• go mod verify, go mod tidy -diff, golangci-lint config verify, and govulncheck run unconditionally and stay green.
• All other steps (lint, vet, test, build, CodeQL, gosec, Semgrep) skip themselves with a log message via the detect job's has-source output.

The first time core/event/event.go (or any other .go file) lands, the detect job flips and the rest of the pipeline activates without any workflow change.

Out of scope (deferred or manual)

• Branch protection rules on main. Cannot be configured in workflow YAML; requires manual setup under repo Settings. docs/ci.md lists the exact required-status-check names and ancillary toggles.
• Self-hosted integration runner. Phase 3+ may revisit if the integration test suite outgrows ubuntu-latest, but spec §14.3 explicitly defers integration tests behind a build tag and runner.
• Container image publishing to ghcr.io. Spec §14.8 says "added when the project starts publishing images" — not v0.1.

Test plan

• Push triggers ci.yml. detect job sets has-source=false. lint runs (go mod verify, go mod tidy -diff, golangci-lint config verify) and passes. test and build jobs skip with the empty-tree message. ci-pass aggregator is green.
• security.yml runs. govulncheck passes. gosec, semgrep, and Trivy gate themselves out / produce empty SARIF. trivy fs runs on the source tree and reports any container/IaC findings (none expected).
• codeql.yml runs. analyze go skips with empty-tree message; check stays green.
• dependency-review.yml runs on this PR. Confirms allowlisted licenses, no high-severity vulns introduced.
• pr-title.yml validates this PR's title against the Conventional Commits spec (ci(workflows): ...).
• scorecard.yml runs on push to main after merge; confirm it shows up in the security tab.
• After merge, set HOMEBREW_TAP_GITHUB_TOKEN (optional) and SCORECARD_READ_TOKEN (optional). Configure branch protection per docs/ci.md.
• Phase 3 (Phase 3: core/event + core/provider #4) lands the first .go file; CI activates the gated steps automatically.

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.