api-contract-architecture

# API Contract Architecture Skill ## 定位 本 Skill 负责 API 契约 Owner 视角。它确保方案先回答“谁消费、契约是什么、如何兼容、如何验证”，再进入实现细节。 ## 触发条件 | 场景 | 是否触发 | |------|:--------:| | 新增或调整 HTTP API、SDK API、CLI 参数、Hook payload、MCP tool/resource、事件、配置 Schema 或 public types | 必须 | | 涉及版本兼容、迁移、错误码、分页、过滤、幂等、鉴权响应或消费者文档 | 必须 | | 修复会影响调用方行为或示例用法 | 必须 | | 纯内部实现且不改变任何公开输入/输出/错误/类型 | N/A + skipReason | ## 核心门禁 | Gate | 要求 | 证据 | |------|------|------| | `ApiContractArchitectureGate` | 公开契约必须有消费者、输入、输出、错��、兼容和验证矩阵 | consumerSurface、contractInventory | | `ConsumerSurfaceGate` | 先列真实消费者，避免首个实现反向定义公共契约 | README、types、examples、route、SDK | | `ErrorModelGate` | 错误结构、错误码、detail 和恢复路径必须稳定 | errorModel、docs | | `CliJsonContractGate` | 机器可读 CLI 必须冻结 envelope 字段、成功/失败互斥、错误码、nextStep 与 native exit code | DevCodexCliEnvelopeV1、spawn fixtures | | `VersionCompatibilityGate` | 兼容、弃用、迁移和 breaking change 必须明确 | versionCompatibility | | `ReleaseAuthorityBeforeCompatibilityGate` | 先证明契约是否已发布并形成稳定消费者，再决定兼容、迁移或直接收敛 | publishedState、consumerEvidence、authoritySources、decision | | `ConfigurationErgonomicsGate` | 公开配置 Schema 必须证明最小任务、字段必要性、复杂度预算和可选字段省略行为 | MinimalTaskConfig、FieldNecessityMatrix、OptionalFieldOmissionProbe | | `ContractVariantIsolationMutationGate` | discriminated union/tool/event/state 合同必须拒绝 sibling variant 字段，并验证完成态必需证据不能被删除或反转 | ContractVariantIsolationMatrix、CompletionEvidenceDeletionMatrix | | `IdempotencyPaginationGate` | 写操作、分页、过滤、排序和重试场景必须定义语义 | idempotencyPagination | ## 执行步骤 1. 列出所有消费者：前端、SDK、CLI、Hook、文档示例、测试、外部...