---
{
  "description": "For projects that explicitly choose PR labels as release intent, project verified compatibility decisions into deterministic version and channel selection.",
  "kind": "policy-skill",
  "name": "pr-label-release",
  "policy_dependencies": [
    "semver-change-governance"
  ],
  "primary_topic": "pr-label-release",
  "public_url_hosts": [],
  "schema_version": 1,
  "slug": "pr-label-release",
  "visibility": "public"
}
---

# PR label release

Use this project policy only when a repository explicitly chooses pull-request labels to declare release intent. It consumes a separately verified compatibility classification; it never derives compatibility from diff size, label presence, or migration file count. Do not install or route this policy for a target-only manual release contract whose single `target` input and trusted final baseline are the version truth.

## Workflow

1. Read the installed `semver-change-governance` policy and verify the release unit's `version-impact` record.
2. Copy and fill `assets/templates/pr-label-release.example.json` with the exact type and channel labels, trusted label gate, release workflow input, durable snapshot/queue behavior, and failure context.
3. Make the label gate a declared required check when `quality-gates` is installed, or record an explicit waiver. Require exactly one supported type label; product types require exactly one supported channel label, while `type:docs` and `type:skip` forbid channel labels.
4. Resolve the next version from the verified maximum impact and the repository's tag history. Keep label validation, version identity, and publication as separate observable steps.

The release workflow must consume the checked-in intent and preserve an auditable snapshot. Notification transport remains a project decision governed by `release-failure-notification`.

## Adoption preview

Before applying this policy to a target project, preview the writes to `.agents/skills/semver-change-governance/`, `.agents/skills/pr-label-release/`, and `skills-lock.json`, then wait for explicit owner approval. Because `npx skills` does not resolve this package's `policy_dependencies` metadata, install the hard dependency first and then this policy:

```text
npx skills add IvanLi-CN/style-playbook-skills --skill semver-change-governance --yes
npx skills add IvanLi-CN/style-playbook-skills --skill pr-label-release --yes
```

The CLI detects the Agent and project layout; the dependency order is part of this policy's adoption contract.

## Package resources

- `assets/templates/pr-label-release.example.json`
- `assets/decision-memos/spotibind-version-only-release-pr.md`

# Decision Memo: SpotiBind `VERSION`-only release PR

## Context

- 目标是在不重写已合并历史、不修改 `main` 保护边界的前提下，为缺少 preparation identity 的已合并产品代码建立下一个可发布 identity。
- 该决策运行在 SpotiBind 的 PR-only `main` / GitHub Actions release surface；本备忘只记录只读回验，不执行合并、tag、GitHub Release、规则或 secret 变更。
- 约束是 `VERSION` 仍为唯一数字源、release identity 不可变，且已有发布失败后的 same-SHA recovery 不得写入 `VERSION`。

## Evidence (from references)

- 相邻可复用发布合同：`skills/style-playbook/references/topics/pr-label-release/TOPIC.md` 与 `skills/policies/pr-label-release/assets/templates/pr-label-release.example.json`。
- 项目发布面：`projects/spotibind.md` 指向其 `.github/workflows/release-preparation.yml`、`release-completion.yml`、`release.yml` 和 `VERSION`；该 snapshot 只证明发布面存在，不替代下列当前只读事实。
- 本次只读事实由任务上下文明确提供：`main/VERSION` 为 `0.1.0`，唯一 release/tag 为 `v0.1.0`；已合并的产品 PR #5 没有 preparation identity；PR #7 是 `type:none` bootstrap，不产生 release。该事实是本备忘的应用输入，不被提升为通用 reference implementation。

## Recommendation (default)

- 选择：在一个单独、受控的 SpotiBind 实现任务先让 `Release completion` 和相关测试识别 `version-only-release-pr` proposal 后，为 PR #5 所代表的单一、尚未准备的产品边界创建一个显式、非空的 `VERSION`-only release PR。该 PR 从当前 `main` 建立，branch diff 只改 `VERSION`，以正常 PR 流程通过完整 CI、`Label Gate`、tag reservation 与该 mode 的 `Release completion` 后 merge。
- 为什么符合既有风格：普通 preparation 已无法回到 PR #5 分支；新 PR 保留 PR-only `main`，让新的 merge SHA 与新 `VERSION` 共同成为不可变 release identity，而不伪造旧 merge 的 provenance。
- 版本选择：先以 release labels 冻结 PR #5 的发布意图，再从 `VERSION=0.1.0` 执行相应写入。自动 patch 才写 `0.1.1`；若语义是 minor/major/RC，必须使用受控 exact 值。tag、历史 release 与 package metadata 都不能作为数字 fallback。
- 风险：把这条路径误称为 same-SHA recovery 或 historical backfill，会再次触发“preparation must modify VERSION only”类结构失败，或让旧 SHA 被错误发布。
- 缓解：新 PR 的 provenance 明确记录 PR #5 的 merge SHA、冻结 intent、目标版本和 `release-mode: version-only-release-pr`；release workflow 只发布该新 PR merge SHA/version。

## Alternatives (1-2)

### Option A: same-SHA recovery for PR #5

- 优点：若 PR #5 已有 immutable release identity 且仅 publish 失败，可避免新 PR。
- 缺点：当前 PR #5 没有 preparation identity，输入不成立；recovery 也禁止修改 `VERSION`。
- 何时选择：仅在一个已锁定的 merged SHA/version 已经存在且发布动作失败时选择。

### Option B: historical backfill or release queue/train

- 优点：历史记录可以补足审计语境；队列在其他发布模型中可安排多个候选项。
- 缺点：两者都不能为本 Topic 分配版本或创建 release identity；queue/train 还会把多条产品边界混为一个发布。
- 何时选择：仅为非发布性的历史审计使用 backfill；本 Topic 不使用 queue/train。

## Follow-ups

- 开放问题：PR #5 对应的 `type:*` / `channel:*` 需要在创建补救 PR 前按实际发布语义确认，不能从改动大小或旧 tag 猜测。
- 下一步：先在独立、明确授权的 SpotiBind 任务中实现并验证该 proposal；随后创建且仅创建上述 `VERSION`-only release PR，其合并后按新 merge SHA/version 进入正常 `Release`。本次备忘不授权任何 GitHub 写入。

{
  "schema_version": 2,
  "policy": {
    "source_of_truth": "pull-request-labels",
    "trusted_gate_workflow": "Label Gate",
    "release_workflow": "Release",
    "failure_notification_workflow": "Notify release failure",
    "label_contract": {
      "type_labels": [
        "type:major",
        "type:minor",
        "type:patch",
        "type:docs",
        "type:skip"
      ],
      "product_types": [
        "type:major",
        "type:minor",
        "type:patch"
      ],
      "non_product_types": [
        "type:docs",
        "type:skip"
      ],
      "channel_labels": [
        "channel:prod",
        "channel:rc",
        "channel:beta",
        "channel:dev"
      ],
      "product_channel_cardinality": "exactly-one",
      "non_product_channel": "forbidden",
      "unknown_or_legacy_values": "fail"
    },
    "version_contract": {
      "version_file": "VERSION",
      "numeric_baseline": "highest-eligible-final-tag",
      "eligible_final_tag_pattern": "^v(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$",
      "version_patterns": {
        "final": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$",
        "prerelease": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)-(beta|rc|dev)\\.[1-9][0-9]*$"
      },
      "eligible_final_tag_requires_main_reachability": true,
      "eligible_final_tag_owner": "protected-release-automation",
      "empty_history_baseline": "0.0.0",
      "formats": {
        "channel:prod": "<base>",
        "channel:beta": "<base>-beta.N",
        "channel:rc": "<base>-rc.N",
        "channel:dev": "<base>-dev.N"
      },
      "base_operations": {
        "type:major": "(X+1).0.0",
        "type:minor": "X.(Y+1).0",
        "type:patch": "X.Y.(Z+1)"
      },
      "prerelease_sequence": "max-published-sequence-plus-one-within-same-base-and-channel",
      "first_prerelease_sequence": 1,
      "prerelease_advances_final_baseline": false,
      "tag_format": "v<version>"
    },
    "release_identity": {
      "fields": [
        "merge_commit_sha",
        "version",
        "channel",
        "tag"
      ],
      "one_per_merge_sha_version_channel": true,
      "identity_claim_key": "pull_request_number+source_sha+type+channel",
      "post_merge_identity_key": "merge_commit_sha+version+channel",
      "one_per_merge_boundary": true,
      "duplicate_merge_boundary": "reuse-existing-identity-or-fail-closed",
      "reservation_claim": "atomic-compare-and-claim",
      "reservation_lifecycle": {
        "id_field": "reservation_id",
        "owner_field": "reservation_owner",
        "claim_key_field": "reservation_claim_key",
        "boundary_token_field": "pre_merge_boundary_token",
        "identity_fields": [
          "version",
          "channel",
          "reservation_merge_commit_sha"
        ],
        "state_field": "reservation_state",
        "states": [
          "claimed",
          "bound",
          "consumed",
          "released"
        ],
        "pre_merge_retry_requires_state": "claimed",
        "claimed_requires_reservation_merge_commit_sha_null": true,
        "recovery_requires_state": "bound",
        "merge_binding_transition": "mainline-release-atomic-claimed-to-bound-when-reservation_merge_commit_sha-is-recorded-and-pre_merge_boundary_token-matches",
        "consumption_transition": "atomic-bound-to-consumed-after-publication-completes",
        "release_transition": "atomic-claimed-to-released-only-if-reservation_merge_commit_sha-is-null-and-pre_merge_boundary_token-is-not-merged",
        "released_reservation_recovery": "forbidden",
        "merge_binding": "mainline-release-atomic-claimed-to-bound-when-reservation_merge_commit_sha-is-recorded-and-pre_merge_boundary_token-matches"
      },
      "tag_ownership": {
        "reserve_before_preparation": true,
        "same_sha_existing_tag_requires_owner": true,
        "same_sha_reservation_requires_owner": true,
        "same_sha_existing_tag": "same-sha-recovery-only",
        "same_sha_unconsumed_reservation": "same-sha-recovery-only",
        "different_sha_existing_tag": "fail-closed",
        "foreign_tag_owner": "fail-closed",
        "incomplete_provenance": "fail-closed",
        "label_channel_mismatch": "fail-closed",
        "unverified_signature": "fail-closed"
      },
      "recovery_reuses_identity": true,
      "recovery_reallocates_version": false
    },
    "channel_publication": {
      "channel:prod": {
        "release_class": "final",
        "deploy_surface": "prod",
        "github_release_prerelease": false,
        "updates_default_surface": true,
        "updates_stable_latest": true,
        "image_tag_policy": "exact-version-tag"
      },
      "channel:rc": {
        "release_class": "prerelease",
        "deploy_surface": "rc",
        "github_release_prerelease": true,
        "updates_default_surface": false,
        "updates_stable_latest": false,
        "image_tag_policy": "exact-version-tag-only"
      },
      "channel:beta": {
        "release_class": "prerelease",
        "deploy_surface": "beta",
        "github_release_prerelease": true,
        "updates_default_surface": false,
        "updates_stable_latest": false,
        "image_tag_policy": "exact-version-tag-only"
      },
      "channel:dev": {
        "release_class": "prerelease",
        "deploy_surface": "dev",
        "github_release_prerelease": true,
        "updates_default_surface": false,
        "updates_stable_latest": false,
        "image_tag_policy": "exact-version-tag-only"
      }
    },
    "contract_update_scope": {
      "task_owned_surfaces": [
        "CONTEXT.md",
        "docs/adr/0003-tag-derived-release-baseline.md",
        "TOPIC.md",
        "pr-label-release.example.json"
      ],
      "real_release_mutations": "forbidden"
    },
    "legacy_migrations": {
      "accepted_only_for_migration": true,
      "accepted_by_new_gate": false,
      "map": {
        "type:none": "type:skip",
        "channel:stable": "channel:prod",
        "channel:canary": "channel:dev"
      }
    },
    "failure_notification_transport_gate": {
      "selection_required": true,
      "accepted_selection_evidence": [
        "checked-in-project-contract",
        "explicit-owner-decision"
      ],
      "when_unselected": "block-rollout",
      "implicit_external_notifier": "forbidden",
      "missing_selected_configuration": "fail"
    },
    "failure_notification": {
      "required_identity_fields": [
        "pull_request",
        "source_sha",
        "merge_commit_sha",
        "type",
        "channel",
        "version",
        "tag",
        "tag_target_sha",
        "tag_owner",
        "reservation_id",
        "reservation_owner",
        "reservation_state",
        "reservation_merge_commit_sha",
        "provenance_verified",
        "signature_verified",
        "branch_head",
        "artifact_names",
        "run_url",
        "recovery_instruction"
      ],
      "recovery_evidence_any_of": [
        [
          "tag",
          "tag_target_sha",
          "tag_owner"
        ],
        [
          "reservation_id",
          "reservation_owner",
          "reservation_state:bound",
          "reservation_merge_commit_sha"
        ]
      ]
    },
    "unknown_release_labels": "fail",
    "duplicate_release_labels": "fail",
    "missing_required_release_labels": "fail",
    "release_identity_modes": {
      "normal_product_pr_preparation": {
        "allowed": true,
        "input": "unmerged-product-pr-after-full-pr-ci-and-label-gate",
        "output": "same-pr-branch-child-commit-that-modifies-version-only",
        "required_provenance": [
          "source-sha",
          "product-version",
          "channel",
          "frozen-release-intent",
          "signed-trailers",
          "branch-head",
          "pr-base",
          "source-ci",
          "tag-reservation",
          "tag-owner",
          "signature-verified"
        ],
        "forbidden": [
          "post-merge-preparation",
          "direct-main-write",
          "product-code-change",
          "multiple-parent-commit"
        ]
      },
      "version_only_release_pr": {
        "allowed": true,
        "implementation_status": "proposal-requires-project-workflow-and-test-adoption",
        "recommended_when": [
          "exactly-one-unprepared-product-boundary-on-mainline",
          "no-preparation-identity-for-that-boundary",
          "no-release-identity-for-that-boundary"
        ],
        "allows_explicit_nonempty_pull_request": true,
        "change_scope": [
          "VERSION"
        ],
        "required_checks": [
          "full-pr-ci",
          "Label Gate",
          "tag-reservation",
          "Release completion"
        ],
        "required_provenance": [
          "covered-product-merge-sha",
          "product-version",
          "channel",
          "frozen-release-intent",
          "release-mode:version-only-release-pr",
          "signed-trailers",
          "branch-head",
          "pr-base",
          "source-ci",
          "tag-reservation",
          "tag-owner",
          "signature-verified"
        ],
        "release_identity": "new-version-only-release-pr-merge-sha-version-channel",
        "release_identity_is_mode_name": true,
        "release_identity_semantics": "canonical-fields-below",
        "release_identity_fields": [
          "merge_commit_sha",
          "version",
          "channel"
        ],
        "forbidden": [
          "empty-pull-request",
          "same-sha-recovery",
          "historical-backfill",
          "direct-main-write",
          "tag-rewrite",
          "multiple-product-pr-aggregation",
          "release-queue",
          "release-train"
        ]
      },
      "same_sha_recovery": {
        "allowed": true,
        "input": "existing-immutable-merged-sha-version-channel-identity-with-same-sha-tag-or-unconsumed-reservation-and-incomplete-publication",
        "output": "retry-publication-for-the-same-sha-version-channel-identity",
        "entrypoint": "workflow_dispatch",
        "requires": [
          "same-sha-tag-or-unconsumed-reservation",
          "verified-tag-owner-or-reservation-owner",
          "complete-provenance"
        ],
        "tag_branch_requires": [
          "same-sha-tag",
          "verified-tag-owner"
        ],
        "reservation_branch_requires": [
          "reservation-id-and-bound-state",
          "verified-reservation-owner",
          "reservation-claim-key-matches",
          "reservation-version-and-channel-match",
          "reservation-merge-sha-equals-recovery-sha"
        ],
        "forbidden": [
          "VERSION-write",
          "new-pull-request",
          "successor-version",
          "preparation-rebuild",
          "tag-rewrite",
          "other-pr-merge"
        ]
      },
      "historical_backfill": {
        "allowed": false,
        "output": "non-release-audit-or-history-record-only",
        "forbidden": [
          "VERSION-write",
          "version-allocation",
          "tag-or-asset-publication",
          "workflow-dispatch-release-entrypoint"
        ]
      },
      "release_queue_or_train": {
        "allowed": false,
        "output": "fail-closed-before-version-allocation",
        "forbidden": [
          "next-pending-selection",
          "multi-product-pr-aggregation",
          "product-pr-reordering",
          "version-reallocation"
        ]
      }
    },
    "persist_release_intent": {
      "mode": "per-release-identity-snapshot",
      "snapshot_artifact": "release-intent.json",
      "recovery_entrypoint": "workflow_dispatch",
      "historical_backfill": "forbidden",
      "queue_strategy": "forbidden",
      "release_train": "forbidden"
    }
  },
  "label_groups": [
    {
      "name": "type",
      "prefix": "type:",
      "required": true,
      "cardinality": "exactly-one",
      "allowed": [
        "type:major",
        "type:minor",
        "type:patch",
        "type:docs",
        "type:skip"
      ]
    },
    {
      "name": "channel",
      "prefix": "channel:",
      "required": false,
      "cardinality": "exactly-one-for-product-types",
      "required_when_type_in": [
        "type:major",
        "type:minor",
        "type:patch"
      ],
      "forbidden_when_type_in": [
        "type:docs",
        "type:skip"
      ],
      "allowed": [
        "channel:prod",
        "channel:rc",
        "channel:beta",
        "channel:dev"
      ]
    },
    {
      "name": "component",
      "prefix": "component:",
      "required": false,
      "cardinality": "zero-or-more",
      "allowed": [
        "component:app",
        "component:web",
        "component:firmware",
        "component:docs"
      ]
    }
  ],
  "release_snapshot": {
    "fields": [
      "pull_request",
      "source_sha",
      "merge_commit_sha",
      "head_sha",
      "branch_head",
      "release_mode",
      "preparation_commit_sha",
      "covered_product_merge_sha",
      "labels",
      "type",
      "channel",
      "components",
      "version",
      "tag",
      "tag_target_sha",
      "tag_owner",
      "reservation_id",
      "reservation_owner",
      "reservation_state",
      "reservation_merge_commit_sha",
      "provenance_verified",
      "signature_verified",
      "artifact_names",
      "run_url",
      "recovery_instruction"
    ]
  },
  "required_quality_gate": {
    "check_name": "Label Gate",
    "quality_gates_declaration": ".github/quality-gates.json"
  }
}