diff --git a/AGENTS.md b/AGENTS.md index 3a6ce8e..e0615ff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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: @@ -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 @@ -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 @@ -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 diff --git a/RELEASING.md b/RELEASING.md index d3ba866..bc18d0b 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -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 @@ -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 diff --git a/ROADMAP.md b/ROADMAP.md index f00bfb6..ba47964 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,9 +1,9 @@ # 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 @@ -11,13 +11,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 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 @@ -25,8 +25,8 @@ this roadmap and `COMPATIBILITY.md`. | --- | --- | --- | | 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. | @@ -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: @@ -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) @@ -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