fix: prevent stale mutable release claims (#34)

Author: tensornull

.github/workflows/ci.yml

@@ -44,10 +44,8 @@ jobs:
         run: uv run pyright
       - name: Run offline unit and contract tests
         run: uv run pytest -m "not live"
-      - name: Check release version agreement
-        run: uv run python scripts/check_version.py --require-changelog
-      - name: Check canonical public content and identity
-        run: uv run python scripts/check_version.py --require-public-preview-docs
+      - name: Check version agreement and durable public content
+        run: uv run python scripts/check_version.py --require-changelog --require-public-preview-docs
       - name: Scan for credentials and scope mistakes
         run: uv run python scripts/check_secrets.py
       - name: Validate workflow syntax with checksum-pinned actionlint

AGENTS.md

@@ -50,10 +50,13 @@ proves only its own evidence layer. Never invent or mock missing evidence.
 
 ## Current milestone: Stable 0.1
 
-Stable 0.1 is complete: `cometapi==0.1.1` is the latest publicly available
-maintenance release, and its release and registry trust chain has been
-verified. Do not begin 0.2 provider adapters without a separate maintainer
-request that authorizes that milestone.
+Verified stable `0.1.x` maintenance releases are available from PyPI. The
+public PyPI registry is authoritative for the latest published version.
+`pyproject.toml` and `.release-please-manifest.json` are authoritative for the
+current repository candidate and must agree; a candidate must not be described
+as published. `ROADMAP.md`, `RELEASING.md`, and `CHANGELOG.md` retain exact
+versions only as dated immutable historical evidence. Do not begin 0.2 provider
+adapters without a separate maintainer request that authorizes that milestone.
 
 Private Remote Validation, the sanitized first history, private initialization,
 pre-visibility closeout, public visibility configuration, Public Preview,
@@ -174,6 +177,12 @@ Post-stable invariants:
     release-link text in both source and built artifact metadata, and require
     each built long description to exactly match the source README. Post-release
     evidence changes must not rewrite README release state.
+11. Never encode a mutable "latest/current published patch version" in
+    persistent guidance or current-state documentation. Query public PyPI when
+    current registry state is required. Keep candidate version truth in
+    `pyproject.toml` and `.release-please-manifest.json`, and keep exact released
+    versions only in immutable historical evidence. The document/version
+    checker must fail before merge or release when this boundary is violated.
 
 ## Repository independence
 
@@ -270,7 +279,7 @@ uv run ruff check src tests scripts
 uv run ruff format --check src tests scripts
 uv run pyright
 uv run pytest -m "not live"
-uv run python scripts/check_version.py --require-changelog
+uv run python scripts/check_version.py --require-changelog --require-public-preview-docs
 uv run python scripts/check_secrets.py
 uv run python scripts/check_workflows.py
 rm -rf dist

CONTRIBUTING.md

@@ -26,7 +26,7 @@ uv run ruff check src tests scripts
 uv run ruff format --check src tests scripts
 uv run pyright
 uv run pytest -m "not live"
-uv run python scripts/check_version.py --require-changelog
+uv run python scripts/check_version.py --require-changelog --require-public-preview-docs
 uv run python scripts/check_secrets.py
 uv run python scripts/check_workflows.py
 rm -rf dist

README.md

@@ -180,7 +180,7 @@ uv run ruff check src tests scripts
 uv run ruff format --check src tests scripts
 uv run pyright
 uv run pytest -m "not live"
-uv run python scripts/check_version.py --require-changelog
+uv run python scripts/check_version.py --require-changelog --require-public-preview-docs
 uv run python scripts/check_secrets.py
 uv run python scripts/check_workflows.py
 rm -rf dist

RELEASING.md

@@ -83,7 +83,7 @@ uv run ruff check src tests scripts
 uv run ruff format --check src tests scripts
 uv run pyright
 uv run pytest -m "not live"
-uv run python scripts/check_version.py --require-changelog
+uv run python scripts/check_version.py --require-changelog --require-public-preview-docs
 uv run python scripts/check_secrets.py
 uv run python scripts/check_workflows.py
 rm -rf dist

ROADMAP.md

@@ -1,6 +1,6 @@
 # CometAPI Python SDK Roadmap
 
-Status: `0.1.2` stable maintenance released
+Status: Stable `0.1.x` maintenance active
 Last updated: 2026-07-30
 Repository contract: this roadmap is self-contained.
 Current gate: maintain the verified stable 0.1 surface. Begin 0.2 only after a
@@ -12,13 +12,13 @@ The SDK provides the shortest reliable path from an OpenAI Python integration
 to CometAPI while preserving official request, response, error, retry, timeout,
 sync, async, and streaming behavior.
 
-Private Remote Validation, Public Preview, the functional `0.1.0a1` Registry
-Alpha, stable `0.1.0`, and maintenance releases `0.1.1` and `0.1.2` are complete
-for the sanitized public repository. Protected repository configuration,
-public default-branch CI, exact-release live smoke, PyPI OIDC publication,
-provenance, digest comparison, and public-registry smoke provide separate
-evidence layers. Only 0.1.x maintenance is active; `0.1.2` does not activate
-0.2 scope.
+Private Remote Validation, Public Preview, the functional Registry Alpha, the
+first stable release, and verified `0.1.x` maintenance releases are complete
+for the sanitized public repository and recorded below as immutable evidence.
+Protected repository configuration, public default-branch CI, exact-release
+live smoke, PyPI OIDC publication, provenance, digest comparison, and
+public-registry smoke provide separate evidence layers. Only 0.1.x maintenance
+is active; no maintenance release activates 0.2 scope.
 Support and release claims remain limited to the evidence defined in this
 roadmap and `COMPATIBILITY.md`.