Governance

Source Text

# Governance

How updates land and what has to be true before published artifacts change.

## Status
- This repository is private for now while changes settle.
- The current public contract version is `0.1.2`.

## Why this exists
Model and dependency details go stale fast. Providers and package ecosystems change often. The workflows and policies here publish dated snapshots from listed upstream sources, with enough evidence to audit what changed.

## Update cadence
- **Daily**: build snapshots for tracked stacks and model files, sync retained state to Cloudflare R2, and upload the `public/` tree to Cloudflare Pages. The read-only `cloudflare-pages-production-cutover.yml` workflow checks the production custom-domain state. Non-main branches stay on the staging Pages preview path.
- **Weekly**: restore the exact retained published docs baseline from the production R2 retained-state bucket, validate retained manifest/file integrity before diffing, hard-fail if no manifest-backed baseline exists, capture refreshed docs for all policy models with doc URLs, and record the retained R2 manifest identity used for the comparison.
- **Manual**: `workflow_dispatch` for urgent updates.

## Python baseline updates
- Python maintenance releases are part of the normal update cadence, on the same footing as SDK, package, and model-source updates.
- The baseline source is `policy/registry.yaml` `source_urls.python_releases` (`https://www.python.org/downloads/`).
- Detection gate: `.github/workflows/python-version-drift.yml` runs `scripts/check_python_version_drift.py` daily and on `workflow_dispatch`. Any drift failure is a hard stop, not a warning.
- Required cutover surfaces for a Python patch update:
  - `policy/registry.yaml` baseline and marker fields.
  - Stack policy Python pins (currently `policy/stacks/google-ai-agents.yaml`).
  - Every workflow `actions/setup-python` pin enforced by the guard.
  - Published constraints/site outputs and any checked-in public or fixture snapshots that embed the Python version in paths or metadata.
- Published/fixture updates must be copied verbatim from generated snapshot outputs. Do not hand-edit JSON fixtures or invent replacement paths.
- Validation evidence for Python baseline cutovers must come from GitHub Actions only:
  - `ci.yml` on the exact PR head SHA.
  - `daily.yml` on the exact PR head SHA because published surfaces change.
  - After merge, `ci.yml` and `daily.yml` on the exact merge SHA, or equivalent proof that the `main` runs used that SHA.
- Every report for a Python baseline cutover must record the PR URL, head SHA, merge SHA, workflow URLs, and proof that each run `headSha` matches the commit it is being used to validate.

## Schema versioning
- JSON schemas live in `schemas/`. Artifact payloads carry `schema_version` fields.
- Schema changes require:
  - A CHANGELOG entry.
  - Backward compatibility notes.
  - New schema versions with explicit migration notes.

## Change policy
- Only listed upstream sources are used for data updates.
- Any data change must be traceable to a source URL.
- Packages are added or removed only through policy changes.
- Repo overlays are accepted only through explicit `policy/repos.yaml` entries.
- Provider identifiers are canonical in policy; published paths use canonical provider names and must be documented.

## Audit files
- Every snapshot must publish `checksums.json`.
- Cosign signatures are published when available.

## Escalation
- Security issues are handled via `SECURITY.md`.