diff --git a/AGENTS.md b/AGENTS.md index 4d5bca4..a6c191f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,29 +18,51 @@ repository. ## 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 +- Remote Git writes are authorized only by the current maintainer request. + Repository documentation may define a workflow, but it never provides + standing permission to push a branch, create or update a pull request, merge, + or perform any other remote mutation. Stop before the first unauthorized + remote write. +- Start each task from a clean worktree. Fetch `origin`, check out local `main`, + require local `main` to be an ancestor of `origin/main`, and fast-forward it + with `--ff-only`. Require the two refs to resolve to the same commit afterward. + If fetching fails, `main` is missing, the worktree is not clean, the ancestry + check fails, the fast-forward fails, or the refs still differ, stop and report + the exact state. +- `dev` is a local-only clean landing branch between tasks. If local `dev` does + not exist, create it only from the checked-out, clean, synchronized `main`. If + local `dev` already exists, require it to be an ancestor of `main`, + fast-forward it with `--ff-only`, and require both refs to resolve to the same + commit. If any check or fast-forward fails, stop and report the divergence; + never reset, rebase, delete, or recreate `dev` to force alignment. Never push `dev`. -- After a topic branch has been merged or otherwise explicitly accepted and - its required verification is complete, treat its active lifecycle as closed. - With a clean worktree, fetch `origin`, fast-forward local `main` to - `origin/main`, fast-forward local `dev` to `main`, and finish with `dev` - checked out. Cleanup is complete only when local `main`, local `dev`, and - `origin/main` resolve to the same commit. +- Use a dedicated short-lived topic branch for each task, created only after + `main` and `dev` are synchronized. Do not commit task changes directly to + `main` or `dev`. +- After an explicitly authorized topic branch has been merged or otherwise + accepted and its required verification is complete, require a clean + worktree, fetch `origin`, check out local `main`, and apply the same ancestry, + `--ff-only`, and exact-ref-equality requirements to `origin/main`, `main`, and + `dev`. If `dev` is absent at cleanup time, create it only from the checked-out, + clean, synchronized `main`. Finish with `dev` checked out. Cleanup is complete + only when `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` - merely to complete this cleanup. If fetching fails, the worktree is dirty, - either fast-forward is impossible, or the three final refs differ, stop and - report the exact state instead of forcing synchronization. + merely to complete lifecycle cleanup. Fail closed and report the exact state + whenever a required cleanliness, fetch, or fast-forward condition is not met. ## Current Milestone: Public Preview -Private Remote Validation is complete, and the current execution target is -Public Preview. Repository-local source, tests, documentation, metadata, -fixtures, workflows, private pull requests, and credential-free CI may be -changed and verified. Stop before changing repository visibility: making the -canonical repository public and configuring or exercising public-only settings, -protected environments, secrets, or live smoke require explicit maintainer -authorization. +Private Remote Validation and Public Preview pre-visibility preparation are +complete. The repository remains private at the visibility authorization gate. +Repository-local source, tests, documentation, metadata, fixtures, and +workflows may be changed and verified locally. Private topic pushes, pull +requests, merges, and credential-free CI are permitted only when the current +maintainer request explicitly authorizes them; this file records scope and does +not grant that authorization. Stop before changing repository visibility: +making the canonical repository public and configuring or exercising +public-only settings, protected environments, secrets, or live smoke require +separate explicit maintainer authorization. The accepted identity is: @@ -265,8 +287,10 @@ reusable workflow path. Repository-local source, tests, documentation, metadata, fixtures, and workflow definitions may be changed and verified locally. Remote repositories, pushes, -tags, releases, npm publication, GitHub or registry settings, and live API -requests require explicit maintainer authorization. +pull requests, merges, tags, releases, npm publication, GitHub or registry +settings, and live API requests require explicit authorization in the current +maintainer request. Repository documents and prior authorizations describe +constraints but do not provide standing permission for a later task. Public identity, contacts, repository metadata, credentials, protection rules, environment approvals, and registry ownership must come from authorized diff --git a/RELEASING.md b/RELEASING.md index d35295d..1f3d6f7 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -83,10 +83,13 @@ complete only when `npm owner ls cometapi` lists the maintainer-confirmed `cometapi-team` account after the first publication; until then this remains a Registry Alpha prerequisite, not a Public Preview blocker. -For the current Public Preview milestone, authorized external actions remain -limited to private pull requests and credential-free CI. Changing repository -visibility and every subsequent public-only configuration or live action -require separate authorization. +For the current Public Preview milestone, private topic pushes, pull requests, +merges, and credential-free CI are the only remote actions that may be +authorized before the visibility transition. This document defines allowable +release mechanics but grants no standing remote-write permission; the current +maintainer request must explicitly authorize each task's remote actions. +Changing repository visibility and every subsequent public-only configuration +or live action require separate authorization. ## Candidate verification gate diff --git a/ROADMAP.md b/ROADMAP.md index 57f72ae..6cb7288 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,7 +1,7 @@ # CometAPI TypeScript and Node.js SDK Roadmap -Status: Public Preview in progress; visibility change awaiting explicit authorization -Last updated: 2026-07-21 +Status: Public Preview pre-visibility complete; visibility change awaiting explicit authorization +Last updated: 2026-07-23 Repository contract: This roadmap is self-contained and is the public source of truth for this repository's release sequence. @@ -11,26 +11,27 @@ The TypeScript and Node.js SDK will provide a typed CometAPI entry point that preserves the official OpenAI JavaScript client experience while shipping a small, auditable package for supported Node.js LTS runtimes. -Private Remote Validation is complete for the sanitized private repository, and -the current execution target is Public Preview. Preparation continues in the -private repository, but work stops before its visibility changes until a -maintainer explicitly authorizes that action. The functional `0.1.0-alpha.1` -prerelease remains a separate evidence gate after Public Preview. Registry -publication proceeds only through Private Remote Validation, Public Preview, -Registry Alpha, and stable 0.1.0 stages. +Private Remote Validation and Public Preview pre-visibility preparation are +complete for the sanitized private repository. The repository remains private +at the visibility authorization gate. Public Preview is not ready until the +visibility transition and all public-only controls and live evidence pass under +separate explicit authorization. The functional `0.1.0-alpha.1` prerelease +remains a separate evidence gate after Public Preview. Registry publication +proceeds only through Private Remote Validation, Public Preview, Registry Alpha, +and stable 0.1.0 stages. ## Milestones -| Milestone | Status | User outcome | -| ---------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| Repository foundation | In progress | The repository has reproducible development, contribution, security, and release processes. | -| 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 | The public repository has blocking CI, repository rules, security reporting, protected environments, and authorized live-smoke evidence. | -| 0.1.0-alpha.1 Registry Alpha | Planned | Early adopters can install a functional prerelease from npm's `next` channel and call the three required OpenAI-compatible resources. | -| 0.1.0 Stable | Planned | Users can install a fully verified package from npm's default channel. | -| 0.2.0 provider-native text | Planned | Users can opt into Anthropic Messages and Gemini text adapters through isolated subpath exports. | -| 0.3.0 CometAPI resources | Planned | Users receive typed access to the first stable CometAPI-specific account or platform resources. | -| Media and task APIs | Later | Users receive typed image, video, audio, upload, polling, and task lifecycle helpers after their contracts are stable. | +| Milestone | Status | User outcome | +| ---------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| Repository foundation | In progress | The repository has reproducible development, contribution, security, and release processes. | +| 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 authorization | The public repository has blocking CI, repository rules, security reporting, protected environments, and authorized live-smoke evidence. | +| 0.1.0-alpha.1 Registry Alpha | Planned | Early adopters can install a functional prerelease from npm's `next` channel and call the three required OpenAI-compatible resources. | +| 0.1.0 Stable | Planned | Users can install a fully verified package from npm's default channel. | +| 0.2.0 provider-native text | Planned | Users can opt into Anthropic Messages and Gemini text adapters through isolated subpath exports. | +| 0.3.0 CometAPI resources | Planned | Users receive typed access to the first stable CometAPI-specific account or platform resources. | +| Media and task APIs | Later | Users receive typed image, video, audio, upload, polling, and task lifecycle helpers after their contracts are stable. | ## Repository Foundation