Skip to content

docs: record Public Preview readiness #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tensornull merged 1 commit into from
Jul 27, 2026
Merged

docs: record Public Preview readiness #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 30 additions & 28 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,13 +50,15 @@ proves only its own evidence layer. Never invent or mock missing evidence.

## Current milestone: Public Preview

Public Preview pre-visibility complete; visibility change awaiting explicit authorization.
Public Preview ready; `0.1.0a1` Registry Alpha awaits explicit authorization.

Private Remote Validation is complete. The sanitized first history, empty
private repository creation, initial push, and pre-visibility closeout are
completed historical steps and must not be repeated. The canonical repository
remains private at the visibility authorization gate. Public Preview is not
ready, and no pre-visibility implementation task remains.
Private Remote Validation, the sanitized first history, private initialization,
pre-visibility closeout, public visibility configuration, and Public Preview
readiness are completed historical steps and must not be repeated. The
canonical repository is public with protected branch and version-tag rules,
Private Vulnerability Reporting, immutable releases, protected environments,
public default-branch CI, and one authorized protected live-smoke result. No
tag, release, PyPI publication, or Registry Alpha claim exists.

The accepted identity is:

Expand All @@ -72,7 +74,7 @@ The accepted identity is:
| Support and conduct | `support@cometapi.com` |
| Security | `https://github.com/cometapi-dev/cometapi-python/security/advisories/new` |

At the visibility authorization gate:
At the Registry Alpha authorization gate:

1. Treat the dependency dispositions recorded in `ROADMAP.md` as authoritative
for the listed pull requests. Process newly opened dependency pull requests
Expand All @@ -82,12 +84,13 @@ At the visibility authorization gate:
3. Keep scheduled and manually dispatched live smoke fail-closed behind
`LIVE_SMOKE_ENABLED=true`, and keep `RELEASE_PLEASE_ENABLED` disabled through
the initial manual alpha.
4. Do not create another pre-visibility closeout pull request unless a current
maintainer request explicitly authorizes a new, scoped change.
5. Stop before changing visibility. After an explicitly authorized visibility
change, repository rules, Private Vulnerability Reporting, protected
environments, default-branch CI, and authorized protected live smoke must
pass before Public Preview can be marked ready.
4. Treat the recorded public rules, security reporting, immutable releases, and
protected environments as readiness invariants. Any drift invalidates the
readiness claim until it is explicitly authorized, restored, and verified.
5. Stop before configuring the PyPI Trusted Publisher, changing release
documentation, enabling Release Please, creating a tag or release, making a
live release request, or publishing to PyPI unless the current maintainer
request separately authorizes the applicable action.

## Repository independence

Expand Down Expand Up @@ -237,21 +240,20 @@ committed.
with shipped behavior. Use currently supported model IDs.
- All repository documentation is written in English.

Before marking Public Preview ready, run
`uv run python scripts/check_version.py --require-public-preview-docs`. The
gate must report every detected violation and fail until canonical identity,
contacts, repository metadata, and durable public-facing content are complete.

The private repository becoming public begins a short configuration interval;
it does not by itself establish Public Preview readiness. After visibility
changes, require pull requests and blocking CI for `main`, with zero required
approvals, blocked force pushes and deletion, and administrator bypass reserved
for emergencies. Protect version tags from updates and deletion, enable
immutable releases and Private Vulnerability Reporting, configure `live-smoke`
without a required reviewer, and configure `pypi` with approval by the current
release approver and self-review allowed. Rerun CI and the authorized protected
live smoke before recording Public Preview readiness or preparing Registry
Alpha.
The Public Preview readiness record requires
`uv run python scripts/check_version.py --require-public-preview-docs` to keep
passing. The gate must report every detected violation and fail until canonical
identity, contacts, repository metadata, and durable public-facing content are
complete.

Before preparing Registry Alpha, re-audit that `main` still requires pull
requests and blocking CI with zero required approvals, force pushes and deletion
remain blocked, administrator bypass remains emergency-only, version tags remain
protected, immutable releases and Private Vulnerability Reporting remain
enabled, and the `live-smoke` and `pypi` environments retain their reviewed
protection boundaries. The one-time Public Preview live opt-in was reset to
false after its successful run; enable it again only for a separately authorized
monitoring request.

Verification reports must list exact commands and outcomes, failed or
unavailable checks, and unverified remote, live, and registry evidence as
Expand Down
59 changes: 26 additions & 33 deletions RELEASING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,8 @@ registry publication. Its recorded CI result is historical evidence, not a
reason to repeat initialization.

The fail-closed content and identity gate was required before the historical
first remote push. Run it again before an explicitly authorized visibility
change and before marking Public Preview ready:
first remote push and passed again before Public Preview readiness. Keep running
it before Registry Alpha preparation and after public-document changes:

```bash
uv run python scripts/check_version.py --require-public-preview-docs
Expand Down Expand Up @@ -194,54 +194,47 @@ Arbitrary-branch and manual publication are forbidden.

## Alpha release checklist

For the current canonical repository, the private initialization and
pre-visibility closeout are completed historical prerequisites. The next
external action is a visibility change, and it requires separate explicit
authorization. This checklist defines dependency order, not standing
permission: every remote mutation, live request, release action, and registry
action must be explicitly authorized in the current maintainer request; stop
otherwise. Maintainers execute authorized steps in order:

1. Confirm the recorded canonical identity, absent `CODEOWNERS`, local gates,
sanitized first history, initial private push, credential-free CI, and
pre-visibility closeout. Do not recreate or repeat those historical steps.
2. Obtain explicit authorization for the visibility change and stop if it is
absent.
3. After the authorized repository visibility change, require pull requests and
blocking CI for `main` with zero required approvals, block force pushes and
deletion, reserve administrator bypass for emergencies, protect version tags
from updates and deletion, enable immutable releases and Private
Vulnerability Reporting, and rerun default-branch CI.
4. Configure `live-smoke` with no required reviewer and `pypi` with approval by
the current release approver and self-review allowed. Set
`LIVE_SMOKE_ENABLED=true`, provide the authorized key, and run the protected
budgeted live smoke. Record Public Preview readiness only after the public
content gate and this live run pass.
5. Confirm ownership of the unscoped PyPI package `cometapi` and configure the
For the current canonical repository, private initialization, pre-visibility
closeout, public visibility, repository protection, environments, public
default-branch CI, and the one-time Public Preview live smoke are completed
historical prerequisites. Do not recreate or repeat them. The next external
actions prepare Registry Alpha and require separate explicit authorization.
This checklist defines dependency order, not standing permission: every remote
mutation, live request, release action, and registry action must be explicitly
authorized in the current maintainer request; stop otherwise.

Before continuing, re-audit the recorded Public Preview invariants: protected
`main` and version tags, immutable releases, Private Vulnerability Reporting,
the `live-smoke` and `pypi` environment boundaries, `LIVE_SMOKE_ENABLED=false`,
absent `CODEOWNERS`, and disabled Release Please. Maintainers then execute the
remaining authorized steps in order:

1. Confirm that the company-managed PyPI identity `dev@cometapi.com` owns or can
create the unscoped PyPI package `cometapi`, and configure the
Trusted Publisher for the exact repository, workflow, and `pypi`
environment.
6. Supply `COMETAPI_KEY`, the approved `COMETAPI_LIVE_MODEL`, and explicit
authorization for the documented four-request, 16-token, 30-second,
2. Confirm the protected `COMETAPI_KEY`, the approved `COMETAPI_LIVE_MODEL`,
and explicit authorization for the documented four-request, 16-token, 30-second,
concurrency-one, stop-on-failure budget before creating the GitHub
prerelease.
7. Replace the pre-release availability notice and source-installation text in
3. Replace the pre-release availability notice and source-installation text in
`README.md` with the release-neutral, maintainer-confirmed sentence
“`0.1.0a1` is approved for PyPI publication.” Date the `0.1.0a1` heading in
`CHANGELOG.md`, remove its candidate/unpublished wording, and rerun every
candidate verification gate, including
`uv run python scripts/check_version.py --expected 0.1.0a1 --require-changelog --require-releasable-docs`.
8. Review the exact candidate and create the immutable SemVer tag
4. Review the exact candidate and create the immutable SemVer tag
`v0.1.0-alpha.1` and corresponding GitHub prerelease. The package and Python
metadata use the equivalent PEP 440 version `0.1.0a1`. This is the canonical
tag spelling; do not use `v0.1.0a1`. After this initial alpha exists, enable
Release Please for later reviewed release pull requests.
9. Allow the release workflow to prove `immutable=true`, resolve the tag to the
5. Allow the release workflow to prove `immutable=true`, resolve the tag to the
checked-out commit, verify that commit is reachable from the protected
default branch, and run the bounded protected live suite against that exact
commit. Only successful completion makes the protected PyPI approval
eligible; approve that job after reviewing its retained artifact digests.
10. Verify publication, provenance, public artifact identity and digest, clean
installation, import, and the public-registry mocked-call smoke.
6. Verify publication, provenance, public artifact identity and digest, clean
installation, import, and the public-registry mocked-call smoke.

Missing credentials, model/budget approval, environments, publisher
configuration, protection, or approval block the publication dependency chain
Expand Down
89 changes: 60 additions & 29 deletions ROADMAP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,32 @@
# CometAPI Python SDK Roadmap

Status: `0.1.0a1` in progress
Last updated: 2026-07-23
Last updated: 2026-07-27
Repository contract: this roadmap is self-contained.
Current gate: Public Preview pre-visibility complete; visibility change awaiting explicit authorization.
Current gate: Public Preview ready; `0.1.0a1` Registry Alpha awaiting explicit authorization.

## Product target

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 and the Public Preview pre-visibility closeout are
complete for the sanitized repository, which remains private. Public Preview is
not ready: the next external action is a separately authorized visibility
change, followed by the required public configuration and protected evidence.
Public Preview and the functional `0.1.0a1` prerelease remain separate evidence
gates. Support and release claims remain limited to the evidence defined in
this roadmap and `COMPATIBILITY.md`.
Private Remote Validation and Public Preview are complete for the sanitized
public repository. Protected repository configuration, public default-branch
CI, and an authorized live smoke establish preview readiness. Public Preview
and the functional `0.1.0a1` prerelease remain separate evidence gates; the next
external actions require separate Registry Alpha authorization. Support and
release claims remain limited to the evidence defined in this roadmap and
`COMPATIBILITY.md`.

## Milestones

| Milestone | Status | Exit outcome |
| --- | --- | --- |
| Repository foundation | Complete | Public files, offline gates, packaging checks, and self-containment are complete. |
| Private Remote Validation | Complete | The sanitized private repository passes real credential-free default-branch CI; public-only controls and live tests remain disabled. |
| Public Preview | Awaiting visibility authorization | Pre-visibility work is complete. After a separately authorized visibility change, the public repository must establish blocking CI, repository rules, security reporting, protected environments, and authorized live-smoke evidence before it claims preview readiness. |
| `0.1.0a1` Registry Alpha | Planned | Early adopters can install a functional prerelease from PyPI. |
| Public Preview | Complete | The public repository has blocking CI, repository rules, security reporting, protected environments, immutable releases, and authorized live-smoke evidence. |
| `0.1.0a1` Registry Alpha | Awaiting authorization | Early adopters can install a functional prerelease from PyPI after every release and registry gate passes. |
| `0.1.0` stable | Planned | Complete runtime, release-PR, example, provenance, and registry gates pass. |
| `0.2.0` provider-native text | Planned | Optional official Anthropic and Gemini adapters. |
| `0.3.0` CometAPI resources | Planned | First schema-backed typed CometAPI-specific resource. |
Expand Down Expand Up @@ -103,20 +103,21 @@ Recorded evidence on 2026-07-21:

## Public Preview

Public Preview pre-visibility complete; visibility change awaiting explicit authorization.
Public Preview ready as of 2026-07-27.

There is no remaining pre-visibility implementation task. Do not create another
closeout pull request without a new, explicit maintainer request. The recorded
dependency dispositions below remain authoritative for the listed pull
requests. Newly opened dependency pull requests remain pending until a current
maintainer request explicitly authorizes their normal maintenance; they must
not cause closed or superseded dispositions to be described as unfinished.
Private initialization, pre-visibility work, the visibility change, public
configuration, and preview evidence are completed historical steps and must not
be repeated. The recorded dependency dispositions below remain authoritative
for the listed pull requests. Newly opened dependency pull requests remain
pending until a current maintainer request explicitly authorizes their normal
maintenance; they must not cause closed or superseded dispositions to be
described as unfinished.

Public Preview is not ready. The repository must remain private until a
visibility change is explicitly authorized. After that change, repository
rules, Private Vulnerability Reporting, protected environments,
default-branch CI, the public-content gate, and authorized protected live smoke
must pass before the milestone can be marked ready.
The milestone was established only after repository rules, Private
Vulnerability Reporting, immutable releases, protected environments,
public default-branch CI, the public-content gate, and an authorized protected
live smoke passed. Registry Alpha remains a separate authorization and evidence
gate.

Recorded pre-visibility dependency dispositions:

Expand Down Expand Up @@ -240,7 +241,7 @@ Failed or unavailable checks:
probe in a fresh detached worktree failed closed before the verified cache was
populated; it is not final-candidate validation evidence.

Remote evidence:
Recorded pre-visibility remote evidence:

- Private PR #9's final-head
[CI run 29916685839](https://github.com/cometapi-dev/cometapi-python/actions/runs/29916685839)
Expand Down Expand Up @@ -272,20 +273,50 @@ Remote evidence:
additional evidence. No visibility, secret, environment, protection, live,
tag, release, registry, or publication change was made.

Live evidence:
Recorded pre-visibility live evidence:

- The live-smoke path was not executed, and no live API request was made.
Transport success and provider behavior therefore remain unverified.

Registry and release evidence:
Recorded pre-visibility registry and release evidence:

- Release Please, immutable-release publishing, PyPI OIDC, provenance, and
public-registry installation were not executed. No tag, release, or
publication was created.

Changing the repository to public begins a short configuration interval; it
does not establish Public Preview readiness by itself. The preview is ready
only when:
Public Preview readiness evidence on 2026-07-27:

- The complete local readiness gate passed on 2026-07-27 with all three
readiness-document changes present: lock reproduction, Ruff, formatting,
Pyright, 200 non-live tests, public-content, secret, workflow, actionlint,
exact wheel and source-distribution, clean-install, and copied
standalone-repository checks all succeeded.
- The canonical repository became public. Active rulesets require pull
requests and the nine blocking CI contexts on `main`, block force pushes and
deletion with organization-administrator emergency bypass, permit only squash
merges, and protect `refs/tags/v*` from updates and deletion.
- Immutable releases and Private Vulnerability Reporting were enabled. The
`live-smoke` environment has no required reviewer; the `pypi` environment
requires the current release approver and permits self-review. The live key
exists only as an environment secret.
- Public scheduled
[CI run 30248141487](https://github.com/cometapi-dev/cometapi-python/actions/runs/30248141487)
passed quality, Python 3.10 through 3.14, minimum and latest-within-major
OpenAI compatibility, package, exact-artifact, retained-digest, and copied
standalone-repository jobs for `fa32e962f7a35dd9e183f7b201bd9117590654a9`.
A manually requested rerun was superseded by this scheduled run through the
reviewed concurrency group and was not used as final evidence.
- Explicitly authorized protected
[live-smoke run 30248383703](https://github.com/cometapi-dev/cometapi-python/actions/runs/30248383703)
passed all four sequential Chat Completions and Responses modes against
`gpt-5.4` within the four-request, 16-output-token, 30-second-per-request,
concurrency-one, zero-retry, stop-on-first-failure budget. The
`LIVE_SMOKE_ENABLED` opt-in was reset to `false` after the run.
- No tag, GitHub release, Trusted Publisher, PyPI OIDC publication, provenance,
or public-registry installation was created or claimed. Release Please remains
disabled through the initial manual alpha.

Public Preview remains ready only while:

- `main` requires pull requests and blocking CI with zero required approvals;
force pushes and deletion are blocked, and administrator bypass is reserved
Expand Down