ci: harden CI matrix, static analysis, supply-chain, and example/doc gates

[dgenio]

Summary

Implements a coherent group of CI / repository-automation issues in one PR.
They all center on .github/ (with supporting Makefile targets, scripts, and
docs), so the shared ci.yml is restructured once instead of conflicting
across seven separate PRs.

Related issues

Fixes #109
Fixes #110
Fixes #165
Fixes #177
Fixes #181
Fixes #187
Fixes #188

What changed

.github/workflows/ci.yml — restructured:

• CI runs the full race+coverage suite twice per push and never cancels superseded runs #187 — push scoped to main, pull_request for branches (no more
  double runs), plus a concurrency group with cancel-in-progress.
• [CI] Run the test suite on a Linux/macOS/Windows matrix #109 — test job now runs a ubuntu/macos/windows matrix with the race
  detector (Go-native invocation so Windows needs no make/POSIX shell);
  coverage is produced and uploaded only from Linux.
• New lint job ([CI] Add gosec and golangci-lint static-analysis gate #110): make fmt-check + golangci-lint (v2.5.0).
• New security job ([CI] Add gosec and golangci-lint static-analysis gate #110/Strengthen supply-chain hygiene with dependency pinning and update automation #177): gosec + govulncheck.
• New examples job (Add an examples-validation CI job that runs every bundled example end to end #181) and docs job (Add a CI doc-claim check that ties README/doc status to actual commands #165).

Static analysis (#110)

• .golangci.yml with a pragmatic linter set; make lint/make golangci/make sec.
• Two real fixes: set ReadHeaderTimeout on the HTTP proxy and metrics
  servers (gosec G112).
• Intentional gosec findings annotated inline with // #nosec <rule> -- <reason>
  (operator-specified file reads, the proxy launching the operator's MCP server,
  forwarding to the configured upstream, non-secret 0o644 files) — no global
  rule disables, so new findings still fail.

Supply-chain (#177) — .github/dependabot.yml (gomod + github-actions,
grouped), a govulncheck job + make vuln, and a SECURITY.md posture section.

Examples (#181) — scripts/check-examples.sh + make examples run every
bundled example (validate / policy test / check / audit verify+summarize+export
/ the demo) through the binary. Hermetic.

Docs (#165) — scripts/check-doc-claims.py + make doc-check verify every
agentfence <subcommand> in the docs is a real command and that local doc
links resolve, with a --selftest that proves the checks fire.

PR triage (#188) — actions/labeler (.github/labeler.yml, existing
labels only) auto-labels PRs by changed path; an advisory check flags
non-Conventional-Commit titles. Documented in CONTRIBUTING.md.

How verified

Locally (Go 1.24, golangci-lint v2.5.0, gosec, govulncheck):

• gofmt -l — clean
• go build ./... — ok
• golangci-lint run ./... — 0 issues
• gosec -quiet ./... — exit 0 (all findings annotated)
• go test -race ./... — all packages pass
• make examples — all examples validated end-to-end
• make doc-check — 11 files: commands + links resolve; --selftest PASS
• All new/edited YAML (ci.yml, pull-request-triage.yml, dependabot.yml,
  labeler.yml, .golangci.yml) parse cleanly.

Could not run locally: govulncheck (the sandbox blocks vuln.go.dev);
it will run in the new security CI job, which has network access.

Risks / notes

• The cross-OS matrix may surface a genuine platform-specific test failure
  (its purpose) — that would be a real finding to address, not workflow noise.
• golangci-lint-action@v8 is pinned to golangci-lint v2.5.0 (matches the
  config schema used locally).
• gosec/govulncheck install via go install @latest in CI so scanners use
  current rules/advisories; Dependabot keeps Actions pinned.

Checklist

• Tests added or updated — new example/doc validation gates; existing race
  suite green
• Documentation updated if needed — CONTRIBUTING.md, SECURITY.md
• CI passes — verified locally; govulncheck runs in CI
• Issue number included

🤖 Generated with Claude Code

https://claude.ai/code/session_01QSZXR9R2Ejmw5FreniZ5yM

---

Generated by Claude Code

[Copilot]

Pull request overview

This PR consolidates several CI and repository-automation improvements centered around .github/, adding cross-platform test coverage, new static-analysis/security gates, and automated checks to prevent example/docs drift—plus supporting Makefile targets, scripts, and documentation updates.

Changes:

• Restructures CI to avoid duplicate runs, add concurrency cancellation, and run tests on a Linux/macOS/Windows matrix (with single-source coverage from Linux).
• Adds dedicated CI jobs for linting, security scanning (gosec + govulncheck), examples validation, and docs claim/link validation.
• Adds Dependabot configuration and PR triage automation (path-based auto-labeling + advisory Conventional Commit title warning), plus targeted gosec-related code hardening/annotations.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
SECURITY.md	Documents supply-chain posture (Dependabot, scanners, signing/SBOM references).
scripts/check-examples.sh	New hermetic script to exercise bundled examples end-to-end against the built binary.
scripts/check-doc-claims.py	New script to verify documented CLI commands exist and relative doc links resolve (with selftest).
Makefile	Adds lint/security/vuln/examples/doc-check targets and tool overrides.
internal/proxy/proxy.go	Adds inline gosec suppression for intentionally operator-specified command execution.
internal/policy/policy.go	Adds inline gosec suppression for operator-specified file reads.
internal/metrics/metrics.go	Adds inline gosec suppression for an intentional/guarded integer conversion case.
internal/httpproxy/httpproxy.go	Hardens HTTP server with ReadHeaderTimeout and annotates intentional proxy forwarding findings.
internal/audit/signing.go	Adds inline gosec suppressions for operator-supplied key paths and intentional public-key perms.
CONTRIBUTING.md	Updates contributor guidance for new CI gates, local targets, and PR triage behavior.
cmd/agentfence/main.go	Adds ReadHeaderTimeout for metrics server; adjusts Close defers and annotates intentional file perms/reads.
.golangci.yml	Introduces golangci-lint configuration (pragmatic linter set + errcheck exceptions).
.github/workflows/pull-request-triage.yml	Adds PR auto-labeling via labeler + advisory Conventional Commit title check.
.github/workflows/ci.yml	Restructures CI triggers/concurrency; adds matrix test + new lint/security/examples/docs jobs.
.github/labeler.yml	Maps changed paths to existing repo labels for auto-labeling.
.github/dependabot.yml	Enables grouped weekly updates for Go modules and GitHub Actions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.