Semantic versioning and release notes management across all Scope components

[cmaneu]

Summary

Write a specification for consistent semantic versioning and release notes management across all Scope components, using a change-fragment workflow such as Changie or Changesets. The spec must cover the complete journey from a developer's change, through PR gates, to a published release and deployment.

This issue delivers the specification and implementation plan—not the production implementation. Tool selection and the versioning model should be explicit design decisions rather than assumed upfront.

Specification scope

1. Component coverage and semantic versioning

• Inventory all Scope components and release artifacts, including CLI, API, Portal, gateway, workers, supporting services, shared packages, containers, database migrations, and deployment assets. Document how documentation and internal-only changes are handled.
• Provide a component matrix identifying version sources, artifacts, publication/deployment destinations, compatibility boundaries, and release grouping. Explicitly justify any exclusions.
• Compare unified, independent, and grouped versioning; recommend a model with trade-offs and dependency-bump propagation rules.
• Define major/minor/patch criteria, public compatibility contracts, pre-1.0 behavior, prerelease versions, deprecations, and breaking-change policies. Cover API/CLI behavior, shared contracts, configuration, and data migrations.
• Explain how component versions, product releases, Git tags, artifact identifiers, and deployed versions map to one another, keeping third-party agent/runtime versions distinct from Scope versions.

2. Tooling and release notes

• Evaluate Changie and Changesets against Scope's multi-component, mixed-language needs, contributor setup, automation, maintenance cost, and support for non-package artifacts. Recommend a tool and document any integration gaps.
• Specify the change-fragment format: affected components, change category, bump intent, user-facing summary, and breaking-change/migration guidance.
• Define fragment aggregation, consumption, and traceability to PRs; generate per-component changelogs and consolidated product release notes from a single source of truth.
• Define publication locations, editorial review, and handling of internal-only changes and security-sensitive announcements.

3. Developer experience

• Describe the contributor workflow for creating, editing, validating, and previewing fragments and proposed version changes locally, including devcontainer setup.
• Minimize manual version edits and changelog merge conflicts; cover multi-component PRs, dependency updates, bot PRs, documentation-only changes, reverts, and backports.
• Include proposed commands, example fragments, actionable validation errors, and required contributor documentation updates.

4. PR gates

• Define when a fragment is mandatory and how a justified no-release-note/no-version-bump exception is requested, reviewed, and audited.
• Specify required checks for fragment schema, valid component identifiers, affected-component coverage, bump intent, and breaking-change migration notes; distinguish automated validation from reviewer judgment.
• Show a PR preview of affected components, planned version changes, and generated notes.
• Define branch-protection integration, behavior for fork/bot PRs and merge queues, and safeguards against stale checks or bypasses. Untrusted PR validation must not require publishing credentials.

5. Release management

• Specify triggers, cadence, release branches or release PRs, approval responsibilities, and stable/prerelease channels.
• Describe version calculation, dependency updates, testing, artifact builds, tagging, publication, release-note generation, and environment promotion—including ordering for coupled components and migrations.
• Define immutable artifact/version traceability, prevention of duplicate releases, concurrent-release handling, idempotent retries, and recovery from partial publication failures.
• Cover hotfixes, backports, rollback/roll-forward, compatibility during staggered deployments, and how operators identify the exact component versions in a release.

Deliverables and acceptance criteria

• A reviewed specification is committed to the repository, with rationale, alternatives, and explicitly recorded decisions.
• A complete component/artifact matrix demonstrates coverage of all Scope components.
• The spec recommends tooling and a versioning strategy, including integration requirements and limitations.
• Contributor workflows, example fragments/release notes, and a PR-gate decision table are included.
• End-to-end walkthroughs cover a patch, a multi-component feature, a breaking API change, a no-release change, a prerelease, a hotfix/backport, and a partially failed release.
• A phased adoption plan defines the initial version baseline, handling of existing tags/changelogs, rollout of enforcement, validation strategy, and implementation work breakdown.

Related context

• Document breaking API changes from per-project data organization (required ?projectId=, removed promptFeatureExtractionId) #1304 documents breaking API changes that need to reach consumers through release notes; use this as a concrete scenario when validating the proposed workflow.