skillhub/openspec/changes/add-skill-suites/specs/skill-suites/spec.md

## ADDED Requirements

### Requirement: Suite SHALL be a typed Namespace resource

系统 SHALL 将 Suite 作为 Namespace 所有的独立资源，并以 `SUITE + namespace + slug` 标识。系统 SHALL 在同一 Namespace 内保持 Suite slug 唯一，但 SHALL 允许 Skill 与 Suite 使用相同 slug。

#### Scenario: Skill and Suite share a slug
- **WHEN** `SKILL @global/marketing` 已存在
- **THEN** 授权用户可以创建 `SUITE @global/marketing`
- **AND** API、URL、搜索结果和 CLI 操作通过资源类型明确区分二者

#### Scenario: Duplicate Suite slug
- **WHEN** 同一 Namespace 已存在 `SUITE @global/marketing`
- **THEN** 系统拒绝再次创建同 slug Suite
- **AND** 返回可操作的冲突说明

#### Scenario: Legacy install remains Skill-specific
- **WHEN** Skill 和 Suite 共用 `@global/marketing`
- **AND** 用户执行 `skillhub install @global/marketing`
- **THEN** CLI 只解析并安装 Skill
- **AND** 只有 `skillhub suite install @global/marketing` 才解析 Suite

### Requirement: SuiteVersion SHALL reference immutable published Skill versions

系统 SHALL 只允许 SuiteVersion 引用同一 Registry 中状态为 PUBLISHED 的精确 SkillVersion，并 SHALL 保存成员坐标、版本和 fingerprint 快照。一个 SuiteVersion SHALL 最多包含 100 个不同 Skill。

#### Scenario: Create a valid SuiteVersion
- **WHEN** 管理者提交不超过 100 个不同的已发布 SkillVersion
- **THEN** 系统创建 DRAFT SuiteVersion
- **AND** 每个 Member 保存精确 SkillVersion ID、坐标、版本、fingerprint 和顺序

#### Scenario: Add a Member without choosing a version
- **WHEN** 作者添加一个 Skill 且没有显式选择版本
- **THEN** 系统向作者推荐当前可安装的最新 SkillVersion
- **AND** 保存前明确展示解析出的版本
- **AND** Member 最终保存为精确 SkillVersion ID、版本和 fingerprint，而不是 `latest`

#### Scenario: Select an older published version
- **WHEN** 作者显式选择一个仍处于 PUBLISHED 且可访问的历史 SkillVersion
- **THEN** 系统允许将该精确版本保存为 Member

#### Scenario: Reject an unresolved or unpublished member
- **WHEN** 成员坐标或版本不存在，或对应 SkillVersion 不是 PUBLISHED
- **THEN** 系统拒绝创建或提交该 SuiteVersion
- **AND** 返回每个无效成员的坐标和原因

#### Scenario: Update Members to currently installable versions
- **WHEN** 作者对 DRAFT SuiteVersion 请求更新 Member 版本
- **THEN** 系统先展示每个拟议版本变化
- **AND** 只有作者确认后才更新 DRAFT 的精确 Member 引用
- **AND** PUBLISHED SuiteVersion 保持不变

#### Scenario: Reject duplicate or excessive members
- **WHEN** SuiteVersion 重复引用同一个 Skill，或成员数超过 100
- **THEN** 系统拒绝该定义
- **AND** 不创建部分成员关系

### Requirement: Entry Skill SHALL be an explicit optional Member

SuiteVersion MAY 指定一个 Entry Skill。指定时，Entry Skill SHALL 精确指向该 SuiteVersion 的一个 Member；系统 SHALL NOT 根据 Suite 和 Skill 的同名关系推断入口。

#### Scenario: Valid Entry Skill
- **WHEN** SuiteVersion 将一个现有 Member 指定为 Entry Skill
- **THEN** 系统保存该精确 SkillVersion 关系
- **AND** Suite 详情和安装计划将其标记为入口

#### Scenario: Entry Skill is not a Member
- **WHEN** 提交的 Entry Skill 不在 Member 集合中
- **THEN** 系统拒绝该 SuiteVersion

#### Scenario: Suite has no Entry Skill
- **WHEN** Suite 仅表示安装集合
- **THEN** 系统允许 Entry Skill 为空
- **AND** 安装后不生成额外的编排 Skill

### Requirement: Member candidates SHALL be filtered by the Server

系统 SHALL 从当前 Registry 的 SkillVersion 数据中提供 Suite Member 候选，并 SHALL 根据当前用户访问权、Skill/Namespace 状态、PUBLISHED 可安装版本、Suite Namespace 和目标 SuiteVersion 可见性在服务端过滤。候选查询 SHALL NOT 泄露用户无权查看的 Skill，v1 SHALL NOT 返回外部 Registry 成员。

#### Scenario: Open the Member picker
- **WHEN** 有投稿权限的用户为 DRAFT SuiteVersion 搜索 Member
- **THEN** 系统只搜索当前用户可读取的 ACTIVE、非 hidden 且具有 PUBLISHED 可安装版本的 Skill
- **AND** 返回精确版本选择以及与目标 Suite 可见性的兼容结果

#### Scenario: Search for an inaccessible private Skill
- **WHEN** 用户搜索自己无权访问的 PRIVATE Skill
- **THEN** 候选查询不返回该 Skill、版本、fingerprint 或其他私有元数据

#### Scenario: Search for a personally accessible but audience-incompatible Skill
- **WHEN** 用户可以访问一个跨 Namespace 的非 PUBLIC Skill
- **AND** 该 Skill 不满足目标 Suite 的受众规则
- **THEN** 系统不允许选择该 Skill
- **AND** 可以向用户说明目标可见性或 Namespace 不兼容，但不得向其他用户暴露该 Skill

### Requirement: Suite SHALL NOT own or mutate Member lifecycle

创建、提交、审核、发布、拒绝、下架、隐藏、归档或删除 Suite SHALL NOT 创建、发布、重新扫描、重新审核、下架、隐藏、归档或删除任何 Member Skill 或 SkillVersion。

#### Scenario: Publish a Suite of existing Skills
- **WHEN** SuiteVersion 通过发布流程
- **THEN** 系统只改变 Suite 和 SuiteVersion 状态
- **AND** 所有 Member 的状态、所有权、统计和审核记录保持不变

#### Scenario: Remove a Suite
- **WHEN** 授权管理者下架、归档或删除 Suite
- **THEN** Member Skill 仍可按其自身权限独立搜索、安装和管理

### Requirement: Suite SHALL use a scan-free version lifecycle

SuiteVersion SHALL 使用 DRAFT、PENDING_REVIEW、PUBLISHED、REJECTED、YANKED 状态，且 SHALL NOT 进入 SCANNING、SCAN_FAILED 或 UPLOADED。PUBLIC 和 NAMESPACE_ONLY Suite SHALL 完成一次 Suite 级审核；PRIVATE Suite SHALL 按现有 PRIVATE Skill 的直接发布原则处理。

#### Scenario: Submit a public Suite for review
- **WHEN** 授权管理者提交有效的 PUBLIC SuiteVersion
- **THEN** SuiteVersion 转为 PENDING_REVIEW
- **AND** 系统创建一个目标类型为 SUITE_VERSION 的审核任务
- **AND** 不为 Member 创建新的审核任务或扫描任务

#### Scenario: Approve a Suite
- **WHEN** 有权限的审核者批准 PENDING_REVIEW SuiteVersion
- **AND** 全部成员仍满足发布条件
- **THEN** SuiteVersion 转为 PUBLISHED
- **AND** Suite.latestVersionId 指向该版本

#### Scenario: Reject a Suite
- **WHEN** 有权限的审核者拒绝 PENDING_REVIEW SuiteVersion
- **THEN** SuiteVersion 转为 REJECTED
- **AND** Member 状态保持不变

#### Scenario: Publish a private Suite
- **WHEN** 授权管理者确认发布有效的 PRIVATE DRAFT SuiteVersion
- **THEN** SuiteVersion 直接转为 PUBLISHED
- **AND** 系统不创建审核或扫描任务

### Requirement: Suite publication SHALL revalidate Member eligibility

系统 SHALL 在提交审核、审核批准和直接发布时重新验证全部 Member 的状态、可见性和访问范围。验证失败 SHALL 保持原状态并阻止发布动作。

#### Scenario: Member becomes unavailable during review
- **WHEN** SuiteVersion 处于 PENDING_REVIEW
- **AND** 一个 Member 在批准前被 YANKED、隐藏、归档或删除
- **THEN** 批准操作失败且 SuiteVersion 保持 PENDING_REVIEW
- **AND** 响应指出阻塞 Member 和当前状态

### Requirement: Published SuiteVersion SHALL be immutable

PUBLISHED 和 YANKED SuiteVersion 的元数据、Member、顺序、Entry Skill、成员版本和 fingerprint 快照 SHALL 不可修改。任何组成变化 SHALL 创建新的 SuiteVersion。

#### Scenario: Member publishes a newer version
- **WHEN** Member Skill 发布一个新版本
- **THEN** 现有 SuiteVersion 仍引用原 SkillVersion
- **AND** Suite 安装不会自动解析到新版本

#### Scenario: Change Suite membership
- **WHEN** 管理者添加、移除、重排 Member 或改变 Entry Skill
- **THEN** 系统要求创建一个新的 SuiteVersion
- **AND** 旧 SuiteVersion 保持不变

### Requirement: Suite visibility SHALL not exceed Member accessibility

SuiteVersion SHALL 保存自身经过审核的可见性快照，其发布范围 SHALL 不得宽于任何 Member 的可访问范围。安装历史版本时 SHALL 使用该 SuiteVersion 的可见性，而不是最新版本的可见性。安装时系统 SHALL 再次对当前用户逐个检查 Suite 和 Member 的实时权限。

#### Scenario: Public Suite contains a non-public Member
- **WHEN** PUBLIC SuiteVersion 包含 NAMESPACE_ONLY 或 PRIVATE Member
- **THEN** 系统拒绝提交或发布
- **AND** 指出可见性不兼容的 Member

#### Scenario: Namespace Suite uses an allowed Member
- **WHEN** NAMESPACE_ONLY SuiteVersion 引用 PUBLIC Member，或同 Namespace 的 NAMESPACE_ONLY Member
- **THEN** 该 Member 通过可见性验证

#### Scenario: Namespace Suite contains a private Member
- **WHEN** NAMESPACE_ONLY SuiteVersion 引用 PRIVATE Member
- **THEN** 系统拒绝提交或发布
- **AND** 即使当前提交者本人可以访问该 Member 也不例外

#### Scenario: Private Suite uses same-Namespace Members
- **WHEN** PRIVATE SuiteVersion 引用 PUBLIC Member，或同 Namespace 的 NAMESPACE_ONLY/PRIVATE Member
- **AND** 操作者具备 Suite Namespace 管理权限和所有 Member 读取权限
- **THEN** Member 通过静态可见性验证

#### Scenario: Suite references a cross-Namespace non-public Member
- **WHEN** SuiteVersion 引用其他 Namespace 的 NAMESPACE_ONLY 或 PRIVATE Member
- **THEN** 系统拒绝提交或发布
- **AND** 不以提交者个人的跨 Namespace 权限替代目标受众校验

#### Scenario: Installer loses Member access
- **WHEN** 用户能够读取 Suite，但当前无权下载至少一个 Member
- **THEN** 安装预检整体失败
- **AND** 不下载或修改任何本地 Skill

#### Scenario: Change Suite visibility
- **WHEN** 管理者希望扩大或收窄已发布 Suite 的可见性
- **THEN** 系统要求创建包含目标可见性的新 SuiteVersion 并走对应审核流程
- **AND** 已发布历史 SuiteVersion 的可见性保持不变

#### Scenario: Install a historical SuiteVersion
- **WHEN** 用户请求安装非最新的 PUBLISHED SuiteVersion
- **THEN** 系统按该历史版本自己的可见性检查 Suite 访问权
- **AND** 继续逐个检查 Member 的当前访问权和可下载性

#### Scenario: Do not disclose inaccessible Member metadata
- **WHEN** 用户能够定位 Suite 但无权查看阻塞的 PRIVATE Member
- **THEN** 安装预检返回不泄露 Member 私有名称、下载地址或元数据的失败信息
- **AND** 有治理权限的管理员可以查看具体阻塞 Member 和原因

### Requirement: Unavailable Members SHALL degrade rather than rewrite a SuiteVersion

Member 在 Suite 发布后变得不可用时，系统 SHALL 保留 SuiteVersion 历史快照并将其显示为 degraded。系统 SHALL NOT 删除成员关系或自动替换为其他版本。

#### Scenario: Member is yanked or hidden after Suite publication
- **WHEN** PUBLISHED SuiteVersion 的 Member 被 YANKED、隐藏或归档
- **THEN** Suite 详情保留原成员坐标和版本
- **AND** 标记该成员不可用及原因
- **AND** Suite 安装预检失败

#### Scenario: Member visibility becomes narrower
- **WHEN** PUBLIC SuiteVersion 的 Member 从 PUBLIC 变为 NAMESPACE_ONLY 或 PRIVATE
- **THEN** SuiteVersion 保持 PUBLISHED 且显示 degraded
- **AND** 新安装整体失败
- **AND** 系统不自动选择该 Skill 的其他版本

#### Scenario: A reversible Member restriction is restored
- **WHEN** Member 因 hidden、archive 或可见范围收窄导致 Suite degraded
- **AND** 后续恢复后该精确 SkillVersion 再次满足 Suite 可见性和安装条件
- **THEN** Suite 自动重新计算为可安装
- **AND** 不创建或修改 SuiteVersion

#### Scenario: A permanently unavailable Member has a newer version
- **WHEN** Suite Member 已 YANKED 或硬删除
- **AND** 同一 Skill 存在其他 PUBLISHED 版本
- **THEN** 原 SuiteVersion 仍保持 degraded
- **AND** 管理者必须创建新 SuiteVersion 才能采用有效版本

#### Scenario: Member is hard-deleted
- **WHEN** PUBLISHED SuiteVersion 引用的 SkillVersion 被治理性硬删除
- **THEN** Suite 历史保留成员坐标、版本和 fingerprint 快照
- **AND** 成员外键可以为空并标记为已删除
- **AND** Suite 安装预检失败

#### Scenario: A deleted coordinate is recreated
- **WHEN** 被硬删除的 Member 后续以相同 namespace、slug 和 version 字符串重新创建
- **THEN** 原 SuiteVersion 不自动关联新 SkillVersion
- **AND** 原成员快照保持 tombstoned 和 degraded
- **AND** 管理者必须创建新 SuiteVersion 才能引用新实体及其 fingerprint

### Requirement: Suite installation SHALL be atomic across Members and targets

CLI SHALL 在修改目标目录前完成全部成员和全部 Agent 目标的解析、权限、冲突和下载预检。CLI SHALL 暂存并校验全部 Member 后统一提交；失败时 SHALL 恢复已有目录和 inventory。

#### Scenario: Install all Members successfully
- **WHEN** 全部 Member 可下载、fingerprint 匹配且目标可写
- **THEN** CLI 将全部 Member 安装到每个选定 Agent 的标准 Skill 目录
- **AND** 一次性记录 Suite 和 Member inventory

#### Scenario: A Member download or fingerprint fails
- **WHEN** 任一 Member 下载失败或 fingerprint 不匹配
- **THEN** Suite 安装整体失败
- **AND** 所有安装前已存在的目录和 inventory 保持不变
- **AND** 不留下已提交的部分 Member

#### Scenario: Commit fails after replacing some targets
- **WHEN** CLI 在文件提交阶段替换部分目标后发生错误
- **THEN** CLI 回滚本次已经替换的全部目标
- **AND** 恢复备份和安装前 inventory
- **AND** 无法完成的回滚必须保留备份路径并明确报告

### Requirement: Suite installation SHALL preserve Agent Skills compatibility

CLI SHALL 将每个 Member 作为普通 Skill 安装到 Agent 已支持的 Skill 根目录。CLI SHALL NOT 为 Suite 创建同名 `SKILL.md` 或要求 Agent 理解 Suite 协议。

#### Scenario: Suite and Skill share a slug locally
- **WHEN** `SKILL @global/marketing` 与 `SUITE @global/marketing` 同时存在
- **AND** 用户安装该 Suite
- **THEN** CLI 只安装 Suite 的 Member
- **AND** 不创建或覆盖 `<skills-root>/marketing/SKILL.md` 作为 Suite 编排文件

### Requirement: Inventory SHALL track shared installation provenance

CLI inventory SHALL 记录已安装 SuiteVersion、精确成员快照，以及每个 Skill 目标的直接安装和 Suite 来源集合。旧 inventory SHALL 能够无损读取并迁移缺省字段。

#### Scenario: A Skill is direct-installed and Suite-installed
- **WHEN** 同一精确 SkillVersion 已直接安装，随后又被 Suite 引用
- **THEN** CLI 复用兼容的本地内容
- **AND** inventory 同时记录 direct 和 Suite 来源

#### Scenario: Multiple Suites share a Member
- **WHEN** 两个已安装 Suite 引用同一精确 SkillVersion 和目标目录
- **THEN** CLI 保留一个成员目录
- **AND** inventory 记录两个 Suite 来源

#### Scenario: Existing inventory has no Suite fields
- **WHEN** CLI 读取升级前的 inventory schema
- **THEN** CLI 将缺失的 Suite 和来源集合按空值处理
- **AND** 已安装 Skill 记录和目标路径保持不变

### Requirement: Suite removal SHALL be ownership-safe

`skillhub suite remove` SHALL 仅移除该 Suite 的来源记录。CLI SHALL 只自动删除不再被直接安装、未被其他 Suite 引用且未被本地修改的 Member 目录。

#### Scenario: Remove an exclusively Suite-installed Member
- **WHEN** Member 仅由被删除 Suite 安装且本地文件未修改
- **THEN** CLI 删除该 Member 目录和对应 inventory 来源

#### Scenario: Preserve a shared or direct-installed Member
- **WHEN** Member 仍有 direct 来源或其他 Suite 来源
- **THEN** CLI 保留 Member 目录及剩余来源

#### Scenario: Preserve a locally modified Member
- **WHEN** 待清理 Member 的当前 fingerprint 与安装基线不同
- **THEN** CLI 保留该目录
- **AND** 报告本地修改和人工处理建议

### Requirement: Suite check and upgrade SHALL use exact snapshots

CLI SHALL 提供 Suite 状态检查和升级计划。升级 SHALL 解析目标 SuiteVersion 的精确 Member 集合并使用与安装相同的原子事务，不得逐个追随 Member latest。

#### Scenario: Check an intact Suite
- **WHEN** inventory、磁盘内容和远端 SuiteVersion 快照一致
- **THEN** `skillhub suite check` 报告最新且完整

#### Scenario: Check a degraded local Suite
- **WHEN** Member 缺失、本地修改、版本不符或远端已不可用
- **THEN** `skillhub suite check` 按 Member 报告差异和阻塞原因

#### Scenario: Upgrade to a new SuiteVersion
- **WHEN** 用户确认从一个 SuiteVersion 升级到另一个版本
- **THEN** CLI 展示成员新增、删除和版本变化
- **AND** 通过原子安装事务应用完整目标快照

### Requirement: Suite governance actions SHALL not cascade to Members

Suite SHALL 支持版本下架、容器隐藏、恢复和归档，并 SHALL 与 Member 治理状态解耦。

#### Scenario: Yank the latest SuiteVersion
- **WHEN** 授权管理者下架 Suite 的最新 PUBLISHED 版本
- **THEN** 该版本转为 YANKED
- **AND** Suite.latestVersionId 重新指向仍可发布的最新 SuiteVersion 或为空
- **AND** Member 状态保持不变

#### Scenario: Hide or archive a Suite
- **WHEN** 管理者隐藏或归档 Suite
- **THEN** Suite 按现有治理规则停止普通发现或新版本操作
- **AND** Member 的发现和生命周期保持不变

### Requirement: Typed discovery SHALL preserve existing Skill search contracts

Suite SHALL 有独立 API 和 Web URL。新的类型化资源发现结果中，每条 Skill 或 Suite 结果 SHALL 返回 `resourceType`。现有 Skill 搜索接口 SHALL 继续只返回 Skill，并保持原响应契约。Suite 详情 SHALL 返回精确版本、成员、Entry Skill、可用性和 degraded 原因。

#### Scenario: Search returns same-slug resources
- **WHEN** 搜索命中同 Namespace、同 slug 的 Skill 和 Suite
- **THEN** 系统返回两条独立结果
- **AND** 每条结果包含不同的 `resourceType` 和详情 URL

#### Scenario: Existing Skill search remains Skill-only
- **WHEN** 旧 CLI 或第三方客户端调用现有 Skill 搜索接口
- **THEN** 响应只包含 Skill
- **AND** 字段、枚举含义和解析行为与引入 Suite 前保持兼容

#### Scenario: Resolve a Suite install plan
- **WHEN** 授权用户通过 Suite 专用接口解析某个版本
- **THEN** 响应包含 SuiteVersion 身份以及有序的精确 Member 版本、fingerprint 和可下载状态

### Requirement: Suite operations SHALL be authorized and audited

Suite 创建、编辑、提交、审核、发布、下架、隐藏、恢复、归档和删除 SHALL 使用现有 Namespace 与平台角色原则，并 SHALL 产生包含 Suite 类型、Suite ID、SuiteVersion ID、操作者和变更摘要的审计记录。

#### Scenario: Unauthorized user modifies a Suite
- **WHEN** 用户不具备该 Namespace 的 Suite 管理权限
- **THEN** 系统拒绝修改且不改变 Suite 状态

#### Scenario: Namespace Member creates a Suite
- **WHEN** 当前 Namespace MEMBER 创建 Suite
- **THEN** 系统允许创建并记录 createdBy
- **AND** 该用户在仍属于 Namespace 时可以维护自己的 DRAFT/REJECTED Suite 和提交新版本

#### Scenario: Suite creator leaves the Namespace
- **WHEN** Suite 创建者不再是 Suite Namespace 成员
- **THEN** createdBy 继续作为审计事实保留
- **AND** 该用户立即失去基于创建者身份的编辑、提交和 PRIVATE Suite 访问权
- **AND** 已发布 Suite、SuiteVersion 和审核记录保持不变
- **AND** Namespace ADMIN/OWNER 可以接管后续维护

#### Scenario: Public user views and installs a public Suite
- **WHEN** 用户访问 PUBLISHED PUBLIC SuiteVersion
- **THEN** 用户可以查看 Suite 公开元数据
- **AND** 只有全部 Member 仍公开且可安装时才能获得完整安装计划

#### Scenario: Namespace member accesses a namespace Suite
- **WHEN** 当前 Namespace MEMBER 访问 PUBLISHED NAMESPACE_ONLY SuiteVersion
- **THEN** 用户可以查看并在全部 Member 校验通过后安装

#### Scenario: Regular member accesses a private Suite
- **WHEN** 普通 Namespace MEMBER 不是 Suite 当前创建者且尝试访问 PRIVATE SuiteVersion
- **THEN** 系统拒绝查看和安装
- **AND** Namespace ADMIN/OWNER 及仍在 Namespace 内的当前创建者可以按规则访问

#### Scenario: Suite review is recorded once
- **WHEN** SuiteVersion 被提交并完成审核
- **THEN** 审核中心记录一个 SUITE_VERSION 审核任务及决定
- **AND** 不为 Member 复制审核记录

### Requirement: Rejected SuiteVersions SHALL preserve review history

REJECTED SuiteVersion MAY 由有权限的管理者退回 DRAFT、修改并重新提交。系统 SHALL 保留每次审核轮次和决定。PUBLISHED 或 YANKED SuiteVersion SHALL NOT 退回可编辑状态。

#### Scenario: Edit and resubmit a rejected SuiteVersion
- **WHEN** 管理者将 REJECTED SuiteVersion 退回 DRAFT、修正成员或元数据并重新提交
- **THEN** 系统创建新的审核轮次
- **AND** 原拒绝决定、审核意见和操作者记录保持可查询

#### Scenario: Attempt to edit a published SuiteVersion
- **WHEN** 管理者尝试修改 PUBLISHED 或 YANKED SuiteVersion
- **THEN** 系统拒绝修改
- **AND** 提示创建新的 SuiteVersion

### Requirement: Suite download metrics SHALL remain attributable and idempotent

一次 Suite 安装计划 SHALL 使用服务端生成的唯一 operation ID 关联 Suite 请求与 Member 下载。服务端成功签发完整安装计划后，SHALL 记录一次 Suite 安装请求，并 SHALL 按现有下载口径为计划内每个 Member SkillVersion 记录一次来源为 SUITE 的下载。同一 operation ID 的重试 SHALL NOT 重复计数。该指标 SHALL 表示服务端计划/下载签发，不得标记为 CLI 本地安装成功。

#### Scenario: Issue a complete Suite install plan
- **WHEN** 服务端完成 Suite 和全部 Member 的权限、状态及可下载性预检并签发完整安装计划
- **THEN** Suite 安装请求数增加一次
- **AND** 每个计划内 Member SkillVersion 下载数按现有口径增加一次并记录 Suite 来源
- **AND** 相关审计记录共享同一个 operation ID

#### Scenario: Suite plan preflight fails
- **WHEN** 服务端因权限、状态或成员不可用而无法签发完整安装计划
- **THEN** 不增加 Suite 安装请求数
- **AND** 不增加 Member 下载数

#### Scenario: Local installation fails after plan issuance
- **WHEN** CLI 在服务端签发计划后因下载、校验或文件提交失败并回滚
- **THEN** 服务端已记录的计划和下载计数保持不变
- **AND** 系统不将这些计数描述为本地安装成功数

#### Scenario: Retry an already recorded operation
- **WHEN** 客户端使用相同 operation ID 安全重试已经记录成功的安装
- **THEN** 系统返回已有计划或幂等成功
- **AND** Suite 和 Member 统计不重复增加

### Requirement: Existing Skill workflows SHALL remain compatible

引入 Suite 后，现有单 Skill 包协议、发布、扫描、审核、URL、API 和 CLI 安装行为 SHALL 保持不变。Suite 专用能力 SHALL 是增量接口。

#### Scenario: Publish and install an ordinary Skill
- **WHEN** 用户在不使用 Suite 的情况下发布并安装一个 Skill
- **THEN** 系统继续使用现有 Skill 生命周期和安装路径
- **AND** 不要求 Suite manifest 或新版 Suite inventory 数据

#### Scenario: Old CLI accesses a registry with Suites
- **WHEN** 不支持 Suite 的旧 CLI 使用现有 Skill API
- **THEN** Skill 搜索、解析、下载和安装仍正常工作
- **AND** 旧 CLI 不会把 Suite 误识别为 Skill

### Requirement: Skill and Suite lifecycle types SHALL remain isolated

系统 SHALL 为 SkillVersion 和 SuiteVersion 使用独立生命周期状态类型。Suite 专属状态 SHALL NOT 改变现有 `SkillVersionStatus` 的字段或枚举含义。Suite 的 degraded 可用性 SHALL 由成员当前状态计算，不得作为对 SkillVersion 状态的反向写入。

#### Scenario: Member availability changes
- **WHEN** PUBLISHED SuiteVersion 的 Member 变为不可安装或重新恢复可用
- **THEN** 系统重新计算 Suite 的可用性和阻塞原因
- **AND** SuiteVersion 的 PUBLISHED 状态保持不变
- **AND** Member SkillVersion 的生命周期状态不被 Suite 修改

#### Scenario: Existing client parses Skill status
- **WHEN** 旧客户端读取引入 Suite 后的 Skill API
- **THEN** 其看到的 Skill 状态枚举和值域与引入 Suite 前一致

### Requirement: Server and CLI versions SHALL fail compatibly

Suite 能力 SHALL 以增量方式提供。旧 CLI 使用新 Server 时 SHALL 保持全部普通 Skill 行为；新 CLI 使用不支持 Suite 的旧 Server 时 SHALL 保持普通 Skill 命令可用，并 SHALL 对 Suite 命令返回明确的不支持结果。

#### Scenario: New CLI uses an old Server
- **WHEN** CLI 请求 Suite 能力而 Server 未声明支持
- **THEN** CLI 停止 Suite 操作并说明 Server 不支持该能力
- **AND** 不将 Suite 命令降级为普通 Skill 安装
- **AND** 普通 Skill 命令仍可使用

#### Scenario: Upgrade a legacy inventory
- **WHEN** 新 CLI 首次向没有 Suite 字段的旧 inventory 写入 Suite 安装结果
- **THEN** CLI 在同一次原子写入中增加新版字段
- **AND** 已有 Skill、目标路径、版本和 fingerprint 记录保持不变

### Requirement: Review storage migration SHALL support rolling compatibility

审核存储从 Skill 专用关联扩展为类型化 subject 时，系统 SHALL 回填现有任务为 `SKILL_VERSION`，并 SHALL 在兼容窗口保留旧 Skill 关联的可读性。数据库迁移 SHALL 为增量迁移，应用回滚 SHALL NOT 要求删除新增 Suite 数据结构。

#### Scenario: Read an existing Skill review after migration
- **WHEN** 数据库迁移前已经存在 Skill 审核任务
- **THEN** 新版本应用仍按原 SkillVersion 读取和处理该任务
- **AND** 其审核决定、权限和审计语义保持不变

#### Scenario: Mixed application versions during rollout
- **WHEN** 部署期间同时存在支持和不支持 Suite subject 的应用实例
- **THEN** 现有 Skill 审核流程保持可用
- **AND** Suite 审核写入只在所有处理实例均支持类型化 subject 后启用