---
{
  "description": "Apply optional SemVer compatibility classification when a change may alter a public API or persistent state; it does not select manual release targets.",
  "kind": "policy-skill",
  "name": "semver-change-governance",
  "policy_dependencies": [],
  "primary_topic": "semver-change-governance",
  "public_url_hosts": [],
  "schema_version": 1,
  "slug": "semver-change-governance",
  "visibility": "public"
}
---

# SemVer change governance

Use this optional project policy when an explicitly selected compatibility scope may change a public API or durable state. It records planned, current, and verified compatibility impact; it does not choose exact version numbers, manual release targets, labels, tags, migrations, release eligibility, or release orchestration. It is not part of the target-only `Manual version release delivery` route.

## Workflow

1. Define the compatibility scope and, when the project chooses to keep a durable assessment, record separate `public_api` and `persistent_state` impacts in `assets/templates/version-impact-record.example.json`. The assessment does not require candidate `base_sha` or `source_sha` fields, one file per PR, or a release-target consumer.
2. Classify each contract as `patch`, `minor`, or `major` using compatibility evidence. Reclassify when scope or supported versions change.
3. Before the compatibility-sensitive change is accepted, verify the declared scope and evidence. A separate adopter may define release-unit aggregation, but this policy does not create a manual-release state or target from it.

## Compatibility rules

- `patch`: public API is nonbreaking; newly written state is readable by all supported earlier versions in the same Minor.
- `minor`: public API stays compatible within the Major; earlier Minor versions need not read newly migrated state, but the candidate must read supported earlier-Minor state.
- `major`: public API may break; state support is limited to the immediately preceding Major. Direct multi-Major jumps require explicit intermediate upgrades.

Keep API and state classifications separate. Migration mechanics belong to `persistent-state-migrations`; version identity and label projection belong to `pr-label-release`.

## Manual release boundary

The target-only `Manual version release delivery` route is intentionally excluded from this policy. It receives one owner-supplied `target` and resolves it from the trusted final baseline; it does not read this assessment, require a repository-local candidate binding, aggregate PR impacts, or persist `maximum_verified_impact` as release state. Projects that explicitly adopt a different compatibility-to-release mapping must document that integration separately and must not infer it from installing this policy.

## Adoption preview

Before applying this policy to a target project, preview the writes to `.agents/skills/semver-change-governance/` and `skills-lock.json`, then wait for explicit owner approval. Install it with `npx skills add IvanLi-CN/style-playbook-skills --skill semver-change-governance --yes`; the CLI detects the Agent and project layout.

## Package resources

- `assets/templates/version-impact-record.example.json`

{
  "schema_version": 1,
  "kind": "version-impact-record",
  "usage": {
    "scope": "optional-compatibility-governance",
    "required_for_manual_release": false,
    "per_pr_release_evidence": false,
    "target_selection": "out-of-scope"
  },
  "change": {
    "description": "<change description>",
    "release_unit_description": "<release unit description>",
    "affected_contracts": [
      "public-api",
      "persistent-state"
    ]
  },
  "classification": {
    "allowed_impacts": [
      "patch",
      "minor",
      "major"
    ],
    "planned": {
      "impact": "patch",
      "reasoning": "<planned compatibility rationale before implementation>",
      "assessed_at": "<RFC 3339 timestamp>",
      "evidence": []
    },
    "current": {
      "impact": "patch",
      "scope_drift": {
        "detected": false,
        "description": "<new surface, changed assumption, or none>"
      },
      "reasoning": "<current compatibility rationale>",
      "reassessed_at": "<RFC 3339 timestamp>",
      "evidence": []
    },
    "verified": {
      "impact": "patch",
      "reasoning": "<release-ready compatibility rationale>",
      "verified_at": "<RFC 3339 timestamp>",
      "evidence": []
    }
  },
  "compatibility_evidence": {
    "public_api": {
      "change": "<none, compatible, or breaking>",
      "supported_consumer_range": "<supported consumer range>",
      "evidence": []
    },
    "persistent_state": {
      "applicable": false,
      "state_description": "<state that survives program versions or not applicable>",
      "source_program_compatibility_range": "<program versions whose compatibility was evaluated>",
      "evidence": []
    }
  },
  "release_unit": {
    "member_change_records": [
      "<record identifier>"
    ],
    "maximum_verified_impact": "patch",
    "calculation_evidence": []
  }
}