Task — engineering-spec@1

"API versioning and deprecation policy"

doneTASK-IMP-056

module improvement · class product · priority p1 · created 2026-07-08 · shipped null
depends on none · blocks none

TASK-IMP-056: API versioning and deprecation policy

Summary

Write a short versioning + deprecation policy for CyberOS 1.x payload HTTP/MCP/CLI surfaces (R10), not platform /v1 service routes.

Problem

Silent breaking changes on MCP tools or CLI verbs become incidents once a second consumer appears.

Proposed Solution

docs/governance/api-versioning.md covering MCP tools, install CLI verbs, docs-tools exit contracts, and workflow enums — with a deprecation window.

Alternatives Considered

Policy for all monorepo /v1 routes — rejected: platform scope (ADR-003).
SemVer tooling automation — rejected: doc policy first.

Success Metrics

Policy names in-scope surfaces and a deprecation checklist.

Scope

Governance doc only.

AI Authorship Disclosure

Session agent; HITL Stephen Cheng (session operator).

1. Description (normative)

1.1 MUST add docs/governance/api-versioning.md scoped to payload MCP/CLI/ docs-tools/workflow surfaces.
1.2 MUST define additive-vs-breaking rules and a minimum deprecation window.
1.3 MUST explicitly mark platform service /v1 routes out of scope.

2. Acceptance criteria

[x] AC 1 (traces_to: #1.1–#1.3) - policy file exists with scope table + deprecation checklist

3. Edge cases

Security emergency may shorten the window only with an ADR + release note.