ci: CI & supply-chain hardening (#141, #195, #202, #205, #208, #209, #210, #212, #225, #232)

[dgenio]

What changed

A single, coherent pass over the build pipeline and repository automation — the
"CI / supply-chain hardening" issue cluster. Closes #141, #195, #202, #205,
#208, #209, #210, #212, #225, #232.

Workflows & automation

• .github/workflows/ci.yml — rewritten: every action SHA-pinned (copied from
  publish.yml) with workflow-level least-privilege permissions (Pin CI actions to commit SHAs and set least-privilege workflow permissions #209); test
  job now invokes make fmt-check/lint/type/test/example so local and CI gates
  cannot drift and all 13 examples run (Align the CI workflow with make ci to eliminate drift #210); pip caching + concurrency
  cancel-in-progress (Speed up CI feedback: add pip/dependency caching and concurrency cancellation #232); new bare-install, security-audit (pip-audit),
  and conformance jobs; per-matrix coverage HTML artifact ([CI] Enforce a coverage threshold and publish a coverage badge #141, Add automated dependency and code scanning (Dependabot, pip-audit, CodeQL) #205, Add a CI job that installs and exercises the bare (no-extras) package #208,
  Activate the weaver-spec conformance suite in CI (replace the placeholder job) #225).
• .github/workflows/codeql.yml — new CodeQL workflow (python,
  security-and-quality, PRs + weekly) (Add automated dependency and code scanning (Dependabot, pip-audit, CodeQL) #205).
• .github/dependabot.yml — new; pip (grouped, range-respecting) +
  github-actions (Add automated dependency and code scanning (Dependabot, pip-audit, CodeQL) #205).
• .github/workflows/publish.yml — CycloneDX SBOM of the published runtime tree
  (separate sbom/ artifact attached to the release; never uploaded to PyPI)
  and PEP 740 PyPI attestations on the Trusted-Publisher upload (Generate SBOMs and build attestations for releases #212).

Code / tests

• pyproject.toml — branch-coverage config with fail_under = 90 (measured
  93.9%), new conformance extra, weaver_contracts.* mypy override ([CI] Enforce a coverage threshold and publish a coverage badge #141, Activate the weaver-spec conformance suite in CI (replace the placeholder job) #225).
• Makefile — make test runs branch coverage + term-missing ([CI] Enforce a coverage threshold and publish a coverage badge #141, Align the CI workflow with make ci to eliminate drift #210).
• tests/test_docstrings.py + tests/test_doctests.py — docstring-shape gate
  over __all__ and curated inline doctests; enriched 3 thin docstrings (Add a docstring-coverage and doctest gate for the public API #195).
• tests/test_architecture.py — stdlib-ast import-boundary rules + 300-line
  module-size ratchet (over-budget files pinned shrink-only) (Add automated architectural conformance checks (import boundaries, module budget) #202).
• src/weaver_kernel/conformance.py + tests/test_conformance.py — maps
  Frame/ActionTrace/CapabilityToken onto the published weaver-contracts
  dataclasses (lazy optional import); validated by real assertions, skipped when
  the extra is absent (Activate the weaver-spec conformance suite in CI (replace the placeholder job) #225).

Docs — README badges + minimal-install/security notes; CONTRIBUTING gate
docs; AGENTS.md architectural-conformance table; RELEASE.md SBOM/attestation
verification; workflows.md CI-calls-make note; CHANGELOG.

Why

These ten issues all share one implementation surface (.github/ + the test
gates) and are far cleaner landed together than as ten near-identical PRs
serially editing the same CI YAML. The grouping rationale is in the triage
report that preceded this PR.

How verified

Local make ci (Python 3.11, venv): all green.

• ruff format --check + ruff check — clean (All checks passed!).
• mypy src/ — Success: no issues found in 58 source files.
• pytest — 730 passed, 1 skipped; branch coverage 93.90%
  (Required test coverage of 90.0% reached).
• All 13 example scripts run via make example.
• New gates verified: import-boundary rule catches a synthetic forbidden edge;
  conformance mapping validates against weaver-contracts 0.7.0; SBOM command
  produces a clean CycloneDX runtime tree.
• All workflow YAML parses; no floating action tags remain in any workflow.

Workflow behavior that cannot run locally (CodeQL upload, Dependabot PRs,
pip-audit network fetch, PyPI attestations/SBOM on a real tag) is exercised by
CI on this PR.

Risks / caveats

• CodeQL action SHA was resolved via git ls-remote github/codeql-action
  (pinned to v3.36.2); first run needs the repo's code-scanning enabled.
• security-audit fails on any known runtime-dep vulnerability by design;
  transient advisories can be allow-listed via pip-audit --ignore-vuln <ID>
  with a comment (documented in README).
• Activate the weaver-spec conformance suite in CI (replace the placeholder job) #225 validates against the published weaver-contracts dataclasses today;
  when dgenio/weaver-spec#4 ships weaver_contracts.conformance, add its
  runner as an extra step in the conformance job (noted inline).
• Generate SBOMs and build attestations for releases #212 uses PyPI (PEP 740) attestations rather than actions/attest-build-provenance
  to avoid an unverifiable new action SHA.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AGeBGThsRwnZuREUV8GoKH

---

Generated by Claude Code

[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.

[Copilot]

Pull request overview

This PR delivers a consolidated “CI / supply-chain hardening” pass across GitHub Actions workflows, test gates, and supporting docs/config, aligning CI with make ci, adding security automation (CodeQL/Dependabot/pip-audit), enforcing coverage/docstring/architecture constraints, and introducing a weaver-spec conformance adapter + tests.

Changes:

• Harden and expand CI: SHA-pinned actions + least-privilege permissions, make-target parity, caching/concurrency, coverage HTML artifacts, bare-install smoke test, pip-audit, and a new CodeQL workflow.
• Add/activate new quality/security gates: branch coverage floor, docstring + curated doctests, and architectural import/module-size enforcement.
• Add conformance mapping (weaver_kernel.conformance) to validate kernel objects against published weaver-contracts, plus documentation updates for release SBOM/attestations and contributor guidance.

Reviewed changes

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

Show a summary per file

File	Description
tests/test_doctests.py	Adds curated doctest execution as a CI-enforced gate.
tests/test_docstrings.py	Enforces docstring presence/shape for weaver_kernel.__all__ exports.
tests/test_conformance.py	Validates kernel→contract mappings against weaver-contracts dataclasses (optional extra).
tests/test_architecture.py	Adds import-boundary and module-size (300-line + ratchet) enforcement.
src/weaver_kernel/replay.py	Docstring enriched to satisfy the new docstring gate.
src/weaver_kernel/ocsf.py	Docstring enriched to satisfy the new docstring gate.
src/weaver_kernel/firewall/token_counting.py	Adds doctested examples for token counting helper.
src/weaver_kernel/federation.py	Docstring enriched to satisfy the new docstring gate.
src/weaver_kernel/conformance.py	New adapter mapping kernel objects to weaver-contracts types.
RELEASE.md	Documents SBOM + PEP 740 attestation generation and verification steps.
README.md	Adds badges and documents CI-enforced minimal-install + security automation.
pyproject.toml	Adds coverage config + conformance extra + mypy overrides.
Makefile	Makes make test enforce branch coverage + term-missing report.
docs/agent-context/workflows.md	Updates workflow docs to reflect CI↔Makefile parity and new CI-only jobs.
CONTRIBUTING.md	Documents coverage/docstring/architecture gates and ratchet policy.
CHANGELOG.md	Summarizes CI hardening and new gates/features in Unreleased.
AGENTS.md	Updates canonical contributor rules (coverage/docstrings/architecture gates, minimal-install claim).
.github/workflows/publish.yml	Adds CycloneDX SBOM generation and enables PyPI attestations.
.github/workflows/codeql.yml	Introduces SHA-pinned CodeQL scanning on PRs + schedule.
.github/workflows/ci.yml	Rewrites CI to use Makefile targets and adds new jobs (bare-install, pip-audit, conformance) + artifacts/caching/concurrency.
.github/dependabot.yml	Adds Dependabot config for pip + GitHub Actions updates.

[dgenio]

Thanks — addressed the review in 00ca6e6:

• conformance.py docstring ref — fixed the cross-reference to weaver_kernel.models.ActionTrace (it's defined in models, only re-imported by trace).
• conformance.py KeyError — trace_to_contract() now raises AgentKernelError with a clear message (and a documented Raises:) on an unknown event_type, per the repo's "no bare KeyError to callers" rule.
• _intra_imports conditional imports — the walker now descends into module-scope if/try/with blocks (a conditional forbidden import is caught), while still skipping TYPE_CHECKING bodies and function/class scope. Verified it catches a synthetic if True: from ..drivers import … in firewall/ and still ignores the TYPE_CHECKING-guarded from .tokens import … in models.py.
• pip-audit auditing its own deps — the security-audit job now resolves the runtime tree in an isolated venv (pip freeze --exclude-editable, minus weaver-kernel/pip/setuptools) and audits that requirements set, so pip-audit's own dependencies are no longer in scope.

On the _SIZE_RATCHET off-by-one: I couldn't reproduce it. Measuring exactly as the test does — len(path.read_text().splitlines()) — every ratcheted file equals its ceiling (e.g. __init__.py = 341, models.py = 753), all files end with a trailing newline, and test_module_size_budget passes on a clean checkout. The ceilings were taken from this same splitlines() count, so I've left them as-is. Happy to revisit if you're seeing a different count in a specific environment.

make ci is green: 730 passed, 1 skipped, 93.87% branch coverage.

---

Generated by Claude Code