docs: adopt the change policy for the API, CLI and config (PR 7e of REORG-PLAN)

[pdettori]

Summary

PR 7e of docs/REORG-PLAN.md: the change policy for the API, CLI and configuration, adopted 2026-10-13. Docs only. Based on main after #505.

docs/reference/change-policy.md records what the repository does today for each surface, defines what counts as a breaking change, and sets the rules: additive-only within a release series, deprecate-then-remove (the longer of one minor release and 90 days for the HTTP API and the sandbox wire contract, 30 days for the CLI, configuration and anything else), runtime warnings, upgrade notes in every release, stored data readable by the previous release, and a breaking change to a Stable surface needing an ADR and sign-off from the CODEOWNERS owner. The eight decisions are tabled with their follow-up issues.

The maturity page marks Stable criterion 5 met; the docs index links the policy.

Follow-up issues (code changes the policy requires)

• Document /turn and /runs as supported aliases of /v1 (move them to the client surface) #507: document /turn and /runs as supported aliases of /v1 (move them to the client surface)
• Add GET /v1/runs/status (keep /runs/status as an alias) #508: add GET /v1/runs/status, keep /runs/status as an alias
• Add a schema-version key to Redis before the first change that needs one #509: add a schema-version key to Redis before the first change that needs one
• Config bundle: carry the format version into the stored bundle and check it on read #510: carry the config bundle format version into the stored bundle and check it on read (BUNDLE_FORMAT_VERSION is 1 and sits in the local lockfile, but the stored bundle drops the lockfile and nothing reads it)
• Define what the OpenAPI info.version means and add a changelog #511: define what the OpenAPI info.version means and add a changelog
• Control plane should not hand a configRef to a harness that cannot apply it #512: the control plane should not hand a configRef to a harness that cannot apply it

Notes

• Several decisions describe behaviour the code does not have yet (Document /turn and /runs as supported aliases of /v1 (move them to the client surface) #507 to Define what the OpenAPI info.version means and add a changelog #511); the page says the follow-ups are open, and the maturity row says criterion 5 is met "though several of its decisions still need code changes".
• I did not touch the code, the route table or the OpenAPI files.

Verification

scripts/check-doc-links.py reports 0 broken links; Prettier run on changed files. make lint not run locally; CI will.

Assisted-By: Claude (Anthropic AI) noreply@anthropic.com

[ingpaolodettori-dev]

Summary

The page is accurate about today's repository: I checked each "What is the contract today" claim against main a02b9db (the route table and the aliases, the once-per-process /run-leaf warning in server.ts:993-1005, both info.version: 1.0.0, mocactl's edge-<sha>/tag/dev version, workspace_key on Exec, the v1. sealed credential, and BUNDLE_FORMAT_VERSION being written to lockfile.json and then stripped by store.ts:51). Issues #507-#512 exist and are open. The comments below cover one decision that contradicts how the aliases are served, one claim that holds for only one of the two OpenAPI files, and a stale criterion in the maturity row this PR edits. None blocks the merge.

Author: pdettori (MEMBER — maintainer)
Areas reviewed: Docs (checked against code on main)
Agent/IDE config (.claude/.vscode): none
Commits: 2 commits, all signed-off: yes
CI status: passing (14/14)

[ingpaolodettori-dev]

suggestion: "frozen … New features appear on /v1 only" can't hold with today's code, and #507 doesn't change that. /turn and /v1/turn go through the same branch (server.ts:1141, handleTurn), and so do /runs and /v1/runs (server.ts:1071). So every addition to /v1 reaches the alias too. That has already happened: detachable turns (#471) work on POST /turn, and #494's workload context works on POST /runs. Either describe the aliases as identical to /v1, including additive changes (that matches how they're served and the word "alias"), or note that freezing them means splitting the handlers. Decision 3 at line 101 needs the same wording.

[ingpaolodettori-dev]

nit: this holds for the data plane only. packages/control-plane/src/routes.ts has no surface field, and its contract test requires every implemented route to be documented (openapi-contract.test.ts, "documents every implemented route"). So docs/api/openapi.yaml describes /internal/credentials (line 728) too. Suggest: "…the data-plane route table marks each route's surface…; the control plane's OpenAPI documents every route, including /internal/credentials."

[ingpaolodettori-dev]

suggestion: this row now marks (5) met, but (3) still says "Not yet: no upgrade or Redis backup guide". #501 shipped docs/operations/upgrades.md and docs/operations/redis-backup-recovery.md for exactly this path. Update (3) as well, for example to "Documented in Operations (upgrades, Redis backup and recovery)", or say what's still missing (the upgrades page states that no rollback procedure is documented). Otherwise the row understates where P6 stands.