Governance

Content (verbatim markdown)

sha256: 6b343091836669df4445f7b6f88725135c724e65f12f75ff90d9d6b4cbdfd509

# Governance

This document describes update cadence and change policy for published registry artifacts.

## Status
- This repository is private for now (next few weeks) while changes continue.
- The current public contract version is `0.2.0`.

## Rationale
LLM training cutoffs make model and dependency details stale. Providers and package ecosystems change frequently. The workflows and policies here exist to publish dated, verifiable snapshots derived from authoritative sources.

## Update cadence
- **Daily**: snapshot build of curated stacks and model artifacts.
- **Weekly**: restore the exact retained published docs baseline from `gh-pages`, validate retained manifest/file integrity before diffing, hard-fail if no retained manifest-backed baseline exists, capture refreshed docs for all policy models with doc URLs, and record the baseline manifest evidence used for the comparison.
- **Manual**: `workflow_dispatch` for urgent updates.

## Python baseline updates
- Python maintenance releases are part of the normal freshness cadence for this registry, on the same operational footing as SDK, package, and model-source updates.
- The authoritative source for the baseline 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/` and are versioned by `schema_version` fields in artifacts.
- Schema changes require:
  - A CHANGELOG entry.
  - Backward compatibility notes.
  - New schema versions with explicit migration notes.

## Change policy
- Only authoritative sources are used for data updates.
- Any data change must be traceable to a source URL.
- Stacks are curated intentionally; packages are added/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.

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

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