Codeman/docs/versioning-policy.md

Versioning & Stability Policy

Codeman follows Semantic Versioning (MAJOR.MINOR.PATCH), managed via @changesets/cli (see the COM workflow in CLAUDE.md).

This document defines what the version number actually promises — i.e. which surfaces are covered by SemVer and which are explicitly not. It exists because "1.0" is a commitment to stability, and an undocumented public surface invites incompatible client assumptions we would then be pressured to keep.

Status: finalized for the 1.0 cut. The HTTP/SSE API is part of the stable surface — served under /api/v1 with a uniform response envelope and conventional HTTP status codes. See api-reference.md.

What SemVer covers (the public, stable surface)

A MAJOR bump is required to break any of these after 1.0:

1. The CLI. Command names, documented flags, and their behavior for codeman <command> (published to npm as aicodeman; invoked as codeman). This is the package's actual public entry point (bin).
   • The package is published to npm as aicodeman and installs both the aicodeman and codeman commands (bin aliases); codeman is the canonical command used throughout the docs. Renaming either after 1.0 is a breaking change.
2. The published xterm-zerolag-input library, but on its own version line — it is versioned and released independently of the Codeman app. Its 1.0 status is a separate decision; the Codeman app reaching 1.0 does not imply xterm-zerolag-input is 1.0.
3. Documented environment variables that configure deployment: CODEMAN_PASSWORD, CODEMAN_USERNAME, CODEMAN_HOST, CODEMAN_PORT, CODEMAN_INSTANCE, CODEMAN_ALLOWED_HOSTS, CODEMAN_DATA_DIR, CODEMAN_TMUX_SOCKET, CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK, CODEMAN_ALLOW_UNAUTHENTICATED_TUNNEL, and the --host / --port / --https / --allow-unauthenticated-network / --allow-unauthenticated-tunnel CLI flags. Removing or changing the meaning of one of these is breaking. The two acknowledgements are listed from 1.46.0, the release that split them: the network one covers the non-loopback bind only, and an unauthenticated tunnel needs the tunnel one.
4. The HTTP API and SSE event channel, served under /api/v1 with the uniform {success:true,data} / {success:false,error,errorCode} envelope and conventional HTTP status codes. Endpoint paths, the response envelope, error errorCode values, and SSE event names are stable — see api-reference.md. Additive changes (new endpoints, new optional fields, new error codes, new SSE events) are non-breaking; breaking changes ship under a new prefix (/api/v2). The unversioned /api/... alias is kept working for the bundled UI.
5. The dashboard's #session=<id> link. Opening the dashboard URL with a #session=<id> fragment selects that session if this client can see it. The fragment name and that meaning are stable; see Opening a session from your own page.

What SemVer does NOT cover (internal surfaces — may change in any release)

These may change in a MINOR (or even PATCH) release without a MAJOR bump:

1. The ~/.codeman/ state file formats (state.json, settings.json, mux-sessions.json, etc.). We make a best-effort to migrate existing data forward (and have done so across renames), but the on-disk schema is not a stable contract — do not write tooling that depends on its exact shape.
2. Internal TypeScript modules. The npm package is CLI-only; importing it programmatically is not supported (there is no stable library entry point).
3. Experimental / opt-in features, regardless of the app's version: Gesture Control (beta), Agent Teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), the native-wrapper window bridge (window.CodemanHost.openWindow / closeWindow / focusWindow), and anything labeled experimental in the UI or docs. These may change or be removed at any time.

Experimental agent coordination

codeman agent inspect, codeman agent stage and codeman agent submit, and the matching GET /api/v1/sessions/:id/inspect, POST /api/v1/sessions/:id/stage and POST /api/v1/sessions/:id/submit routes (with their /api aliases, since every /api route is also served under /api/v1), are labeled experimental, so item 3 above applies to them: their commands, flags, endpoint paths, payloads and behavior may change or be removed in a MINOR or PATCH release. They are also opt-in: the routes answer 403 FORBIDDEN with a message naming the synced agentCoordinationEnabled setting (default OFF) until it is turned on, so automation cannot come to depend on them without choosing to. Pin a compatible Codeman version when automating them. Existing authentication, ownership and shared response-envelope rules still apply. The session behavior underneath them (input revision tracking in the session's write paths, the SubmitVerifier re-press going through the shared write boundary) runs for every session and is covered like any other stable behavior. Other agent commands and API routes keep their existing guarantees. Promotion to stable requires an explicit documented decision.

Experimental local model routes

GET /api/v1/local-model, POST /api/v1/local-model/install, /cancel, /resume and /runtime, and DELETE /api/v1/local-model (and their /api aliases) are labeled experimental, so item 3 above applies to them: their paths, their payloads (the hardware facts, the verdicts and reasons, the candidate fields, the install object with its states, steps, error codes and actions, the 409 conflict shape and every English sentence) and their behavior may change or be removed in a MINOR or PATCH release. They look at the Mac the server runs on, say which local model fits, and install, start, stop and remove one (local-models.md).

They are not behind a setting. Reading changes nothing; an install starts only on an explicit request that carries the size the person confirmed. All of them are admin only in multi-user mode. What an install leaves behind is ordinary, stable state: one saved model endpoint with the id local-ollama and the customModelEndpointsEnabled setting switched on, both of which the stable custom model endpoint routes read like any other endpoint. On-disk state (local-model.json, the local-model/ folder) is internal, as for every other file in the data directory. Promotion to stable requires an explicit documented decision.

Deprecation policy

When we need to change a covered surface:

• Prefer additive changes (new flag/env var/command) over breaking ones.
• A covered surface slated for removal is deprecated first — it keeps working for at least one MINOR release with a runtime warning and a CHANGELOG.md note pointing to the replacement — then removed in the next MAJOR.
• Back-compat migration shims (e.g. the historical Claudeman→Codeman data/socket migration) are kept until a MAJOR boundary, then may be dropped.

Pre-1.0 (0.x) caveat

Until 1.0 ships, any release may contain breaking changes per SemVer's 0.x allowance. The commitments above take effect at 1.0.0.

See also

• CLAUDE.md — the COM release workflow (changesets, version bump, deploy)
• .github/SECURITY.md — security reporting and the supported-version policy
• docs/security-architecture.md — the full trust model