diff --git a/AGENTS.md b/AGENTS.md index 4cad57a..3a6ce8e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,49 +3,60 @@ This file is the self-contained engineering contract for the public CometAPI Python SDK repository. Treat this directory as the repository root. -## Repository authority +## Repository authority and remote permissions -Repository-local source, tests, documentation, metadata, fixtures, and workflow -definitions may be changed and verified locally. The current milestone may use -private pull requests and credential-free GitHub Actions to complete the -remaining pre-visibility work. Changing repository visibility, configuring -secrets or environments, making live API requests, creating tags or releases, -publishing to PyPI, and changing registry settings remain outside the current -authorized pre-visibility scope. +Repository documents define permitted workflows and safety boundaries; they do +not grant standing permission to change local tracked content or remote state. +Any push, pull-request creation or update, merge, comment, or other remote +mutation requires explicit authorization in the current maintainer request. +Without new explicit authorization, limit work to local read-only inspection or +validation and do not create another pre-visibility closeout pull request. + +Repository visibility, settings, branch or tag rules, Private Vulnerability +Reporting, secrets, variables, environments, live API requests, tags, releases, +PyPI operations, and other registry operations each require separate explicit +authorization. Authorization for one action does not authorize another. A local build, mocked test, statically valid workflow, or private remote CI run proves only its own evidence layer. Never invent or mock missing evidence. ## Git branch lifecycle -- Use a dedicated short-lived topic branch for each task. `dev` is the clean - local landing branch between tasks; do not commit task changes directly to - `dev`. +- Start every authorized task from a clean worktree. Fetch `origin`, switch to + local `main`, require `main` to be an ancestor of `origin/main`, and run + `git merge --ff-only origin/main`. Require the worktree to remain clean and + `main` to equal `origin/main` after the fast-forward. +- If local `dev` does not exist, create it with `git switch -c dev` only while + the synchronized, clean `main` is checked out. If local `dev` exists, require + `dev` to be an ancestor of `main`, switch to `dev`, and run + `git merge --ff-only main`. Require `dev` to equal `main` after either path. +- Only after those startup checks pass may an authorized task create its + dedicated short-lived topic branch from synchronized `dev`. Do not commit + task changes directly to `dev`. - Treat a topic branch lifecycle as closed only after its required pull-request checks pass and its squash merge is present on `origin/main`. Any alternate disposition requires explicit user authorization and must not advance `dev` until the accepted commit is present on `origin/main`. -- With a clean worktree, fetch `origin`, switch to `main`, and fast-forward it - with `git merge --ff-only origin/main`. Require the worktree to remain clean - and `main` to equal `origin/main` before handling `dev`. If local `dev` - exists, require it to be an ancestor of `main`, switch to it, and fast-forward - it with `git merge --ff-only main`; if it does not exist, create it with - `git switch -c dev` only from that checked-out, clean, synchronized `main`. - Finish with `dev` checked out. Cleanup is complete only when the worktree is - clean and `HEAD`, local `main`, local `dev`, and `origin/main` resolve to the - same commit. -- Never reset, discard work, force-update refs, delete branches, or push `dev`. - If fetching fails, the worktree is dirty, `main` cannot fast-forward to - `origin/main`, an existing `dev` cannot fast-forward to `main`, or the four - final refs differ, stop and report the exact state instead of forcing - synchronization. +- After merge and required verification, start from a clean worktree, fetch + `origin`, switch to `main`, require it to be an ancestor of `origin/main`, and + fast-forward it with `git merge --ff-only origin/main`. Require `main` to + equal `origin/main`, require `dev` to be an ancestor of `main`, switch to + `dev`, and fast-forward it with `git merge --ff-only main`. Finish on a clean + `dev` with `HEAD`, local `main`, local `dev`, and `origin/main` all equal. +- Any dirty worktree, fetch failure, ahead or divergent local branch, failed + ancestry check, failed fast-forward, or final ref mismatch must fail closed. + Never reset, rebase, discard work, force-update refs, delete or recreate an + existing `dev`, or push `dev` to recover. Report the exact state instead. ## Current milestone: Public Preview -Private Remote Validation is complete. Prepare the private canonical repository -for a future explicitly authorized visibility change, and stop before changing -visibility. A session starting in this repository must be able to finish the -remaining pre-visibility work without instructions outside the repository. +Public Preview pre-visibility complete; visibility change awaiting 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. The accepted identity is: @@ -61,22 +72,22 @@ The accepted identity is: | Support and conduct | `support@cometapi.com` | | Security | `https://github.com/cometapi-dev/cometapi-python/security/advisories/new` | -Before changing repository visibility: +At the visibility authorization gate: -1. Resolve or explicitly defer every dependency disposition that `ROADMAP.md` - still records as unresolved; its pre-visibility dependency disposition table - is the durable source of truth. +1. Treat the dependency dispositions recorded in `ROADMAP.md` as authoritative + for the listed pull requests. Process newly opened dependency pull requests + through normal maintenance only when a current maintainer request explicitly + authorizes that work, without reopening completed dispositions. 2. Keep `.github/CODEOWNERS` absent until a real multi-maintainer model exists. 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. Run every local offline, package, self-containment, public-content, secret, - and workflow-static-validation gate, then deliver the pre-visibility changes - through a private pull request with successful credential-free CI. -5. Confirm the canonical repository is still private and stop. Visibility, - branch or tag rules, Private Vulnerability Reporting, secrets, protected - environments, Trusted Publishing, live API calls, tags, releases, and - publication require separate authorization after this stop point. +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. ## Repository independence @@ -226,7 +237,7 @@ committed. with shipped behavior. Use currently supported model IDs. - All repository documentation is written in English. -Before Public Preview, run +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. diff --git a/RELEASING.md b/RELEASING.md index da804da..d3ba866 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -18,11 +18,14 @@ upload is evidence only for its own layer. ## Private Remote Validation -Before Public Preview, initialize an empty private repository from a sanitized -first commit. Do not ask GitHub to generate a README, license, or ignore file. -The complete history must already be suitable for public visibility. +The canonical repository has completed Private Remote Validation. This section +records its one-time initialization history; it is not an instruction to +recreate the repository, rewrite the sanitized first history, or repeat the +initial push. The repository was initialized empty from a sanitized first +commit, without a generated README, license, or ignore file, and the complete +history was required to be suitable for public visibility. -Apply these canonical values before the first push: +The one-time initialization used these canonical values before the first push: | Field | Required value | | --- | --- | @@ -35,24 +38,28 @@ Apply these canonical values before the first push: | Support and conduct | `support@cometapi.com` | | Security | `https://github.com/cometapi-dev/cometapi-python/security/advisories/new` | -The package manifest uses `authors = [{ name = "CometAPI" }]`. Remove -`.github/CODEOWNERS` and its validation dependencies; it is not required while -the project has one active maintainer. - -Before the first push, require `LIVE_SMOKE_ENABLED=true` for scheduled and -manually dispatched live execution, and keep `RELEASE_PLEASE_ENABLED` disabled -through the initial manual alpha. An unset or non-true value prevents the -corresponding gated job from executing. The release live-model configuration -resolves an unset or empty `COMETAPI_LIVE_MODEL` to `gpt-5.4`. - -The private stage validates sanitized history, the complete local gate, and -real credential-free default-branch CI only. Do not configure or exercise -branch or tag rules, Private Vulnerability Reporting, secrets, protected -environments, Trusted Publishing, live API calls, tags, releases, or registry -publication. Record the CI result and stop before changing visibility. - -Run the fail-closed content and identity gate before the first remote push and -again before changing repository visibility: +The package manifest uses `authors = [{ name = "CometAPI" }]`. +`.github/CODEOWNERS` and its validation dependencies were absent from the +completed private initialization and remain unnecessary while the project has +one active maintainer. + +Before the historical first push, scheduled and manually dispatched live +execution was required to fail closed unless `LIVE_SMOKE_ENABLED=true`, and +`RELEASE_PLEASE_ENABLED` was kept disabled through the initial manual alpha. An +unset or non-true value prevents the corresponding gated job from executing. +The release live-model configuration resolves an unset or empty +`COMETAPI_LIVE_MODEL` to `gpt-5.4`. + +The completed private stage validated sanitized history, the complete local +gate, and real credential-free default-branch CI only. It did not configure or +exercise branch or tag rules, Private Vulnerability Reporting, secrets, +protected environments, Trusted Publishing, live API calls, tags, releases, or +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: ```bash uv run python scripts/check_version.py --require-public-preview-docs @@ -92,6 +99,10 @@ verification record. ## Final post-merge evidence +This procedure grants no standing permission for remote writes. Run it only +when the current maintainer request explicitly authorizes the pull-request +lifecycle and its final timeline comment. + After a pre-visibility pull request is squash-merged, complete its evidence record against the resulting default-branch commit: @@ -183,19 +194,24 @@ Arbitrary-branch and manual publication are forbidden. ## Alpha release checklist -Maintainers execute this sequence in order: - -1. Complete the canonical identity table, replace unresolved public status - text, remove `CODEOWNERS` and its checks, and run the local content, - self-containment, package, secret, and workflow gates. -2. Create the empty private repository, push the sanitized first history, wait - for real credential-free default-branch CI, record its result, and stop for - explicit visibility-change authorization. -3. After the repository becomes public, 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. +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 diff --git a/ROADMAP.md b/ROADMAP.md index be265a1..f00bfb6 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -3,6 +3,7 @@ Status: `0.1.0a1` in progress Last updated: 2026-07-23 Repository contract: this roadmap is self-contained. +Current gate: Public Preview pre-visibility complete; visibility change awaiting explicit authorization. ## Product target @@ -10,11 +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 is complete for the sanitized repository, which -remains private. The current pre-visibility phase stops before any visibility -change. 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 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`. ## Milestones @@ -22,7 +25,7 @@ defined in 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 | In progress | Pre-visibility work is delivered through private pull requests; after an 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. | +| 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. | | `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. | @@ -57,12 +60,15 @@ Exit criteria: ### Private Remote Validation -Before Public Preview, maintainers create a private repository from a -sanitized first commit and verify real GitHub behavior. The complete history -must already be suitable for future public visibility and contain only durable -product, contribution, maintenance, compatibility, and release material. +Private Remote Validation was the one-time initialization stage for the +canonical repository. Maintainers created an empty private repository from a +sanitized first commit and verified real GitHub behavior. The complete history +was required to be suitable for future public visibility and contain only +durable product, contribution, maintenance, compatibility, and release +material. This stage is complete and must not be repeated for the current +canonical repository. -Exit criteria: +Recorded exit criteria: - Canonical repository metadata, `CometAPI` authorship, `Copyright (c) 2026 CometAPI`, `support@cometapi.com`, and the repository's @@ -77,9 +83,9 @@ Exit criteria: environments, registry publisher, live credential, tag, release, or package publication is configured or exercised during this private stage. -The private repository is created empty, without generated starter files, so -the sanitized local content becomes its first history. This stage ends after -real credential-free default-branch CI is recorded. It does not change +The private repository was created empty, without generated starter files, so +the sanitized local content became its first history. The stage ended after +real credential-free default-branch CI was recorded. It did not change visibility or publish to a private or public registry. Recorded evidence on 2026-07-21: @@ -97,20 +103,22 @@ Recorded evidence on 2026-07-21: ## Public Preview -Public Preview is in progress at the pre-visibility stage. Before requesting a -visibility change: +Public Preview pre-visibility complete; visibility change awaiting explicit authorization. + +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. -- Deliver all remaining documentation and workflow changes through private pull - requests with credential-free CI. -- Review every open dependency pull request. Fix and merge only updates with - complete successful CI; otherwise record an explicit deferral and keep the PR - out of `main`. -- Rerun the complete local gate and private pull-request CI, confirm the - canonical repository remains private, and stop for explicit visibility-change - authorization. Do not configure public-only controls, secrets, environments, - live smoke, releases, or publication before that stop point. +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. -Pre-visibility dependency disposition: +Recorded pre-visibility dependency dispositions: | Item | Disposition | Evidence and required action | | --- | --- | --- |