convex-launch-readiness

发布准备就绪报告

准备就绪并非单项检查，而是多项检查的并集，经过去重、排序和评分。本能力纯粹基于 findings 总线（specs/finding.schema.json）进行组合：它会运行各项审计能力，将其输出规范化为一份报告（specs/finding-report.schema.json），计算可审计的分数；并且由于每条 finding 都指定了一个 fixCapability，会向用户提供按优先级排列、可执行的待办清单，而不是四份单独的报告。本能力本身不会修复任何问题；它负责确定要修复什么以及修复顺序，然后分派给修复工具。

工作流

1. GUARD + SCOPE：由 deploy-guard 对目标进行分类（local-anonymous / dev / preview / prod）；并告知用户。检测可评估的内容——是否存在 convex/ 目录、是否有正在接收流量的已部署 deployment、是否有认证基础？跳过前置条件不满足的检查，并明确说明跳过了哪些（跳过的检查不算通过）。
2. 运行各项检查，每项都会在总线上生成 findings：
   • convex-authz — 授权扫描（identity-from-arg、missing ownership、PII leak、parent-ref-on-write）。代码始终可供扫描。
   • convex-reviewer — validators、indexes-not-filter、惯用写法、错误处理。代码始终可供检查。
   • convex-advisor — 实时 read-limit / OCC 证据（仅当存在正在接收流量的 deployment 时运行；否则记录 'skipped: no traffic'）。
   • convex-insights — 日志中的近期故障（仅当存在 deployment 时运行）。 并发运行互不依赖的检查；每项检查返回 findings，而非修复方案。
3. 规范化 + 去重：将所有 findings 汇总到一份报告中。将每条 finding 的 identity 字段设为规范化的函数/表键（例如 messages:list），确保无论检查报告的是代码位置还是 deployment 位置，该字段都相同——这样，同一缺陷从两个位置被发现时（reviewer 在代码位置报告索引缺失，advisor 在 deployment 位置报告其 read-limit 症状），会通过总线的 (class, identity) 去重合并为一条，不会在评分中重复计数。保留置信度较高的来源。不得悄然丢弃任何内容；检查出错或被跳过，意味着存在明确说明的覆盖缺口，而不是检查结果正常。
4. 评分，可审计：从 100 分开始；按严重程度对每条已确认的 finding 扣分（高 −15，中 −5，低 −1），最低为 0；打印准确的公式和每类问题的扣分明细，确保分数可复现，而非凭感觉。仅有可能性的 findings 列为候选项，但不会影响分数（以证据为依据，而非凭感觉）。没有 deployment / 流量的运行应报告仅基于代码的分数，并明确说明这一点。
5. 报告：先列出分数，然后按严重程度排列 findings，每条都附上证据、位置、fixCapability 和一句修复说明。按“阻断项”（高）/“应修复项”（中）/“锦上添花项”（低）分组。最后列出有序修复计划：接下来运行哪项能力以及运行顺序（先修复授权/数据丢失问题，再处理性能/扩展性问题，最后处理惯用写法/可观测性问题）。
6. 按请求分派：对于用户接受的每条 finding，调用其 fixCapability（convex-authz、convex-reviewer 的修复工具、用于 schema 变更的 migrate-rehearse、用于组件替换的 suggest）。修复后，重新运行受影响的检查并展示分数变化——只有修复问题时准备就绪分数会随之变化，这个分数才有意义。
7. 绝不声称覆盖范围超过实际运行的检查：报告标题列出已运行、已跳过的检查及跳过原因。仅基于代码的运行即使分数为绿色，也表示“代码看起来已准备就绪”，而非“已通过生产环境验证”。

规则

• 组合使用，不要重新实现：运行现有的审计能力并汇总它们的总线发现结果——切勿在行内重新推导授权或性能检查。
• 评分只统计已确认的发现，并按严重程度计算，同时打印公式；可能存在的发现只是候选项，不影响分数。
• 去重前，将每项发现的位置规范化为函数／表的标识（映射部署端的 functionId ↔ 代码文件:行号），这样同一缺陷在两个位置被发现时会合并为一项，不会重复计分；保留置信度较高的来源；不得悄然丢弃任何内容。
• 每项发现都要附带其 fixCapability；报告最后要列出有序修复计划（先处理数据丢失／授权问题，再处理扩展性，最后处理惯用法／可观测性）。
• 修复后重新运行受影响的检查，并展示分数变化——修复问题后准备度分数却不变，就是在作秀。
• 绝不声称运行了实际未运行的检查：标头列出已运行／已跳过的检查；仅运行代码检查时，得分仅代表代码检查，并明确标注。
• 这是一个读取、汇总和分派的检查阶段；修复由修复能力完成，并受其自身的授权同意／部署目标规则约束。