docs(change-plan): 收紧 schema 选择判断机制

Author: sincerely90

plugins/aisee-plugin/skills/aisee-change-plan/evals/evals.json

@@ -25,6 +25,7 @@
         "使用 Mermaid 语法块表达依赖顺序和并行关系。",
         "保持摘要、Mermaid 图、change 详情块和命令区的 change/phase 数量一致。",
         "使用 /opsx:new \"<change>\" --schema <schema>。",
+        "给出 schema 裁决，说明为什么选中该 schema、为什么不选至少一个替代 schema。",
         "保留 RBAC 复用事实和邀请链接过期规则待确认项。",
         "说明后续通过 aisee:change-author 或 /opsx:continue 补齐 artifacts。"
       ],
@@ -36,6 +37,7 @@
         "change 边界",
         "Mermaid 依赖图",
         "依赖顺序",
+        "Schema decision",
         "Metadata gate",
         "source-map seed",
         "/opsx:new 命令"
@@ -47,6 +49,7 @@
       ],
       "quality_checks": [
         "change 边界来自可独立交付能力，不来自文档标题。",
+        "schema 选择理由与替代 schema 拒绝理由都可追溯到输入事实。",
         "待确认规则不被主观补全为实现决策。"
       ],
       "fact_source_constraints": [
@@ -70,13 +73,15 @@
         "判断为单个小 change。",
         "输出一个 change 详情块、单节点 Mermaid 依赖图和单条 /opsx:new 命令。",
         "保持摘要、Mermaid 图和命令区的计数一致。",
+        "给出 schema 裁决，并明确为什么不需要升级成 aisee-app-spec-driven。",
         "说明不需要为了流程拆成多个 change。"
       ],
       "must_ask": [
         "状态枚举是否已有并可复用？"
       ],
       "must_include": [
         "单 change 判断",
+        "Schema decision",
         "Mermaid 依赖图",
         "Out of Scope",
         "/opsx:new 命令"
@@ -88,6 +93,7 @@
       ],
       "quality_checks": [
         "保持小需求小处理。",
+        "schema 选择必须解释为什么没有 API / DB / 完整 UI 契约足迹。",
         "清楚标注复用现有列表页和权限。"
       ],
       "fact_source_constraints": [
@@ -110,6 +116,7 @@
       "expected_outputs": [
         "拒绝把背景、UI 页面、API 设计、数据库设计、测试计划或上线计划作为 change 边界。",
         "围绕退款处理、退款报表、退款状态查看规划 change。",
+        "给出每个 change 的 schema 裁决和至少一个替代 schema 的拒绝理由。",
         "每个 change 包含 FR 引用、Out of Scope、source-map seed 和 Mermaid 依赖图。"
       ],
       "must_ask": [
@@ -118,6 +125,7 @@
       ],
       "must_include": [
         "FR 引用",
+        "Schema decision",
         "Mermaid 依赖图",
         "Out of Scope",
         "source-map seed",
@@ -151,6 +159,7 @@
       "expected_outputs": [
         "保留 [ARCHITECTURE-DECISION-REQUIRED]。",
         "把库存一致性策略作为 blocker 或首个风险验证/决策 change。",
+        "如果 schema 选择仍有决定性歧义，应输出 schema blocker，而不是硬选 schema。",
         "避免直接规划依赖未知一致性方案的实现 change。"
       ],
       "must_ask": [
@@ -159,6 +168,7 @@
       ],
       "must_include": [
         "[ARCHITECTURE-DECISION-REQUIRED]",
+        "Schema decision",
         "Mermaid 依赖图",
         "blocker 或决策 change",
         "受影响 FR"
@@ -169,6 +179,7 @@
       ],
       "quality_checks": [
         "架构 blocker 不被降级为普通风险。",
+        "schema 选择不会借由未确认架构决策被偷渡成既定事实。",
         "规划结果可防止后续 change-author 建立在错误前提上。"
       ],
       "fact_source_constraints": [
@@ -191,6 +202,7 @@
       "expected_outputs": [
         "选择或建议 aisee-device-spec-driven。",
         "输出设备类 source-map seed，包含 HW/FW/RT/VER 或 TBD in 对应 contract。",
+        "给出为什么不选择 aisee-app-spec-driven 或 quick-fix 的理由。",
         "把板级引脚和传感器型号未确认标为 blocker 或 Open Question。"
       ],
       "must_ask": [
@@ -199,6 +211,7 @@
       ],
       "must_include": [
         "aisee-device-spec-driven",
+        "Schema decision",
         "HW/FW/RT/VER",
         "blocker 或 Open Question"
       ],
@@ -215,6 +228,123 @@
         "device source-map seed 不是正式硬件设计。"
       ],
       "files": []
+    },
+    {
+      "id": "change-plan-006",
+      "name": "dont-downgrade-contractful-change-to-quick-fix",
+      "scenario": "misleading-small-change",
+      "prompt": "用户说这是个小修复：登录失败提示文案顺便优化一下。但真实需求还包括：连续失败 5 次后锁定账号 15 分钟、返回剩余锁定时间、记录管理员可查询的审计日志。请规划 change-plan。",
+      "context": {
+        "files": [],
+        "assumptions": [
+          "用户的“小修复”说法与真实范围不一致。",
+          "锁定策略和审计查询属于正式产品能力。"
+        ]
+      },
+      "expected_output": "不得因为用户说是小修复就选择 quick-fix。应识别到这项需求涉及新的认证策略、服务语义和审计能力，优先选择 aisee-app-spec-driven，并在 schema 决策中明确拒绝 quick-fix。依赖顺序和执行命令如需输出，仍必须使用 Mermaid 和 /opsx:new。",
+      "expected_outputs": [
+        "识别用户表述与真实契约足迹不一致。",
+        "选择 aisee-app-spec-driven，而不是 quick-fix。",
+        "在 Schema decision 中明确拒绝 quick-fix 的原因。"
+      ],
+      "must_ask": [
+        "账号锁定策略和管理员审计查询是否都属于本次交付范围？"
+      ],
+      "must_include": [
+        "aisee-app-spec-driven",
+        "Schema decision",
+        "拒绝 quick-fix 的理由",
+        "/opsx:new 命令"
+      ],
+      "must_not": [
+        "不得因为“小修复”措辞直接选择 quick-fix。",
+        "不得省略认证或审计契约影响。"
+      ],
+      "quality_checks": [
+        "schema 选择基于真实契约足迹，而不是用户的缩小措辞。",
+        "锁定策略与审计能力被视为正式实现契约。"
+      ],
+      "fact_source_constraints": [
+        "change-plan 只能根据给定需求判断契约足迹，不生成额外认证规则。"
+      ],
+      "files": []
+    },
+    {
+      "id": "change-plan-007",
+      "name": "keep-feasibility-work-in-quick-research",
+      "scenario": "research-vs-implementation",
+      "prompt": "我们想评估是否接入某第三方 OCR 服务，用来识别报销票据。当前目标只是比较 3 家供应商、验证识别准确率和费用模型，并给出 go/no-go 建议。请规划 change-plan。",
+      "context": {
+        "files": [],
+        "assumptions": [
+          "当前阶段只做可行性研究，不承诺生产实现。"
+        ]
+      },
+      "expected_output": "应选择 quick-research，而不是 aisee-app-spec-driven。输出的问题、发现和建议导向的 schema 决策，不得把供应商接入、上线改造或正式 API 实现写成当前 change 的生产任务。",
+      "expected_outputs": [
+        "选择 quick-research。",
+        "在 Schema decision 中说明为什么不进入 app 实现 schema。",
+        "保持结论是研究 / go-no-go，而不是生产任务。"
+      ],
+      "must_ask": [
+        "这次是否只产出供应商评估和建议，不进入生产接入？"
+      ],
+      "must_include": [
+        "quick-research",
+        "Schema decision",
+        "go/no-go",
+        "拒绝 aisee-app-spec-driven 的理由"
+      ],
+      "must_not": [
+        "不得输出生产实现任务。",
+        "不得承诺正式接入第三方 OCR 服务。"
+      ],
+      "quality_checks": [
+        "schema 选择不会把调研结论升级成实现任务。",
+        "替代 schema 的拒绝理由与当前目标一致。"
+      ],
+      "fact_source_constraints": [
+        "评估目标来自输入事实；change-plan 不补造上线范围。"
+      ],
+      "files": []
+    },
+    {
+      "id": "change-plan-008",
+      "name": "block-on-unresolved-schema-ambiguity",
+      "scenario": "schema-selection-blocker",
+      "prompt": "帮我规划“修复文件上传不稳定”这个需求。现有信息只有：有时用户上传失败；可能是前端重试逻辑、后端鉴权、对象存储权限、CI 打包配置或病毒扫描超时导致。没有稳定复现，也没有确认是只修问题还是要顺便重做上传链路。请直接给我 schema 和 change-plan。",
+      "context": {
+        "files": [],
+        "assumptions": [
+          "当前证据不足以稳定判断是 quick-fix、infra-change、security-audit 还是 aisee-app-spec-driven。"
+        ]
+      },
+      "expected_output": "不得硬选 schema。应提出最多 1 个决定性问题，或直接输出 [SCHEMA-SELECTION-BLOCKED]，列出仍在竞争的 schema 及原因，并明确在 schema 未定前不能输出 /opsx:new 命令或进入 change-author。",
+      "expected_outputs": [
+        "输出 [SCHEMA-SELECTION-BLOCKED] 或一个决定性澄清问题。",
+        "列出仍在竞争的 schema 及其 plausible 理由。",
+        "在 schema 未定前不输出 /opsx:new 命令。"
+      ],
+      "must_ask": [
+        "这次目标是先定位根因并回答 go/no-go，还是已经确认要做生产修复/重构？"
+      ],
+      "must_include": [
+        "[SCHEMA-SELECTION-BLOCKED]",
+        "Candidate schemas still in contention",
+        "Decisive question"
+      ],
+      "must_not": [
+        "不得硬选 quick-fix、infra-change、security-audit 或 aisee-app-spec-driven。",
+        "不得在 blocker 状态下输出 /opsx:new 命令。"
+      ],
+      "quality_checks": [
+        "低置信度 schema 选择被阻断，而不是被包装成确定结论。",
+        "blocker 明确说明误选 schema 会导致的错误后续流程。"
+      ],
+      "fact_source_constraints": [
+        "在根因和目标未确认前，不得把任何一个候选 schema 升级为既定事实。"
+      ],
+      "files": []
     }
   ]
 }

plugins/aisee-plugin/skills/aisee-change-plan/references/output-template.md

@@ -10,6 +10,8 @@
 4. 全部命令
 5. 整体理由
 
+如果任何 change 的 schema 选择仍处于低置信度竞争状态，不输出正常 change plan，改为输出 `Schema Selection Blocker` 报告并停止在 planning。
+
 ## 摘要
 
 ```text
@@ -59,8 +61,21 @@ Complexity:   S | M | L
 Description:
   用一句话说明该 change 交付什么。
 
+Schema decision:
+  - Selected schema: <selected-schema>
+  - Alternative schemas considered:
+      - <schema-a> — reject because ...
+      - <schema-b> — reject because ... / No credible alternative
+  - Confidence: high | medium
+  - Decisive signals:
+      - 交付意图: ...
+      - 契约足迹: ...
+      - 上游追踪: ...
+      - 风险/不确定性: ...
+
 Schema rationale:
   - 为什么选择该 schema。
+  - 为什么不是上面的替代 schema。
   - 如果不是 aisee-app-spec-driven，说明为什么不需要 SRS / UI Content / Architecture 追踪。
   - Required upstream docs: SRS / UI Content / Design Spec / Design Assets / Architecture / Issue / PR / none
 
@@ -129,6 +144,30 @@ Command:
 ─────────────────────────────────────────────────
 ```
 
+## Schema Selection Blocker 模板
+
+当 schema 仍有决定性歧义时，输出以下阻断报告，替代正常 change plan：
+
+```text
+[SCHEMA-SELECTION-BLOCKED]
+Change: <candidate-change-name-or-scope>
+Why blocked:
+  - 说明为什么当前事实不足以稳定选择 schema。
+Candidate schemas still in contention:
+  - <schema-a> — why plausible
+  - <schema-b> — why plausible
+Decisive question:
+  - 只问 1 个能改变 schema 选择的问题；若用户未答，停止，不输出 /opsx:new
+Impact:
+  - 说明如果误选 schema，会导致哪些错误 artifact 或错误流程
+```
+
+规则：
+
+- 出现 `[SCHEMA-SELECTION-BLOCKED]` 时，不输出 `全部命令`。
+- 出现 `[SCHEMA-SELECTION-BLOCKED]` 时，不提示进入 `aisee:change-author`。
+- 不要一边声明 blocked，一边继续给可执行 `/opsx:new` 命令。
+
 ## 全部命令
 
 ```bash
@@ -163,6 +202,11 @@ Assumption 格式：
 - 摘要中的 `{M}` 必须等于 Mermaid 图中的 phase 数量。
 - `全部命令` 中的 `/opsx:new` 数量必须等于 change 数量。
 - Mermaid 图中的每个 change 都必须有对应详情块和对应命令。
+- 每个 change 都必须有 `Schema decision`，且至少写出 1 个被拒绝的替代 schema；若没有可信替代，明确写 `No credible alternative`。
+- `Schema decision` 中的 `Confidence` 只允许 `high` 或 `medium`；若只能给 `low`，必须改为 `[SCHEMA-SELECTION-BLOCKED]`。
+- 选择 `quick-fix` 时，不得同时要求完整 app/device source-map 字段或 Required=yes 的 app 契约 artifacts。
+- 选择 `quick-research` 时，不得输出生产实现任务、上线步骤或生产代码承诺。
+- 选择 `aisee-device-spec-driven` 时，不得输出以 Web/API/DB 为主体的 source-map seed。
 - 每个 change 的 `Metadata gate` 都必须同时包含：
   - `/opsx:new must use: /opsx:new "<change>" --schema <selected-schema>`
   - `后续 author / implementation 只读取 change metadata 中固化的 schema，不根据 artifacts 猜测或重选`

plugins/aisee-plugin/skills/aisee-change-plan/references/schema-selection-rules.md

@@ -17,6 +17,55 @@
 | 设备 / 固件 / 嵌入式 / 驱动 / 板级 | `aisee-device-spec-driven` | Linux 设备程序、RTOS、bare-metal、MCU、SoC、板级 bring-up 或硬件相关 change |
 | 普通 OpenSpec change | `spec-driven` | 不需要 Aisee 规划链追踪，且项目未安装更合适轻量 schema |
 
+## 必做判定维度
+
+每个 change 在选 schema 前，至少按以下维度内部审查一次：
+
+| 维度 | 要判断什么 | 常见信号 |
+|---|---|---|
+| 交付意图 | 是生产实现、轻量修复、调研结论、文档维护，还是基础设施/安全工作 | “上线功能”“修一个问题”“回答可行性”“改 docs”“改 CI / 部署 / 权限” |
+| 可观察结果 | 用户、操作者、系统或设备最终能看到什么变化 | 新能力、修复后的行为、调研结论、审计报告、部署策略、硬件行为 |
+| 契约足迹 | 是否需要新增或显著修改 UI / API / DATA / HW / FW / RT / VER 契约 | 新接口、数据模型变化、前端状态流、设备协议、验证合同 |
+| 上游追踪 | 是否需要稳定追踪 SRS / UI Content / Design Spec / Architecture / hardware context | 需要把前置 planning docs 压缩进后续实现 contract |
+| 风险与不确定性 | 是否仍在回答 go/no-go、根因未明、架构/安全决策未定 | spike、PoC、待确认、一致性策略未定、第三方集成未知 |
+| 规模与 owner | 是否单一 owner、预计时长、是否跨多个域 | <=1 天单点修复、跨团队共享前置、横跨 app + infra + security |
+
+不要只看用户表面措辞。用户说“只是小改”但如果已经包含新 API / 数据 / 权限 / 设备契约，就不是 `quick-fix`。
+
+## 结构化裁决规则
+
+每个 change 必须输出一个明确的 schema 裁决，而不是只写一句“推荐 X schema”：
+
+- 至少列出 `Selected schema` 和 `Alternative schemas considered`。
+- 至少写出 1 个被拒绝的候选 schema；若确实只有 1 个合理候选，明确写 `No credible alternative`。
+- `Selected schema` 的理由必须回到上面的判定维度，而不是重复工作类型名称。
+- 被拒绝 schema 的理由必须可操作，例如“会错误要求 source-map / specs”“会把调研结论升级成实现任务”“缺少安全 threat-model”“无法承接 HW/FW/RT/VER”。
+
+推荐的最小内部裁决表：
+
+| 候选 schema | 结论 | 关键理由 |
+|---|---|---|
+| `quick-fix` | reject | 需要新增服务契约和审计语义，超出单点修复 |
+| `aisee-app-spec-driven` | select | 需要 source-map、specs、tasks，并承接 SRS / Architecture 追踪 |
+
+## 低置信度阻断
+
+当以下任一情况成立时，不得硬选 schema；先问最多 1 个决定性问题，或直接输出 `[SCHEMA-SELECTION-BLOCKED]`：
+
+- 两个 schema 都看起来合理，且选择不同 schema 会改变后续 artifact 形态。
+- 当前证据无法判断它是生产实现还是调研 / 风险验证。
+- 当前证据无法判断它是 app 业务变更，还是 infra/security/device 主导变更。
+- 根因未明，可能跨 `quick-fix`、`infra-change`、`security-audit` 或 `aisee-app-spec-driven`。
+- 用户显式指定 schema，但输入事实明显指向另一个 schema，且是否接受该风险会影响 author 阶段。
+
+`[SCHEMA-SELECTION-BLOCKED]` 最小内容：
+
+- `Change`
+- `Why blocked`
+- `Candidate schemas still in contention`
+- `Decisive question`
+- `Do not run /opsx:new yet`
+
 ## App Schema v2
 
 `aisee-app-spec-driven` 的最小闭环：
@@ -41,7 +90,7 @@
 
 - 使用用户指定 schema。
 - 每个 change block 和每条 `/opsx:new` 命令都必须一致使用该 schema。
-- 在 `Schema rationale` 中说明该 schema 是否匹配。
+- 在 `Schema rationale` 中说明该 schema 是否匹配，并至少给出 1 个替代 schema 为什么没有被选。
 - 如果指定 schema 明显过重或过轻，只输出风险提示，不擅自改 schema。
 
 ## Availability Preflight
@@ -58,9 +107,31 @@ schema 状态检查只使用 `aisee schemas list/check --json`。
 
 混合系统可以同时需要 app 与 device schema，但每个具体 change 仍只能选择一个 schema。不要为了省事把云端、App、设备和固件塞进一个超大 change。
 
+## 一致性反查
+
+选完 schema 后，必须做一次反查；若反查失败，说明 schema 选错了或边界还没定清：
+
+- 选择 `quick-fix` 时：
+  - 不应需要新的 `service-contract.md`、`data-model.md`、`ui-contract.md` 或完整 `source-map.md` 追踪。
+  - 不应把新业务能力、跨模块契约或多阶段落地写进 In Scope。
+- 选择 `quick-research` 时：
+  - 不应输出生产实现任务、上线步骤或承诺交付生产代码。
+  - 应把结论写成问题、发现、建议或 go/no-go。
+- 选择 `infra-change` 时：
+  - 核心交付应是环境、部署、流水线、运行时配置或回滚控制，而不是面向用户的新业务能力。
+- 选择 `security-audit` 时：
+  - 核心交付应围绕威胁、控制、审计或安全验证；不要把它弱化成普通功能迭代。
+- 选择 `aisee-app-spec-driven` 时：
+  - 应确实需要 `source-map.md`、`specs/**/*.md`、`tasks.md` 这套追踪闭环。
+- 选择 `aisee-device-spec-driven` 时：
+  - 应出现 HW / FW / RT / VER 线索；不要回退成 Web/API/DB 主体。
+
+若反查发现矛盾，优先修正 change 边界；边界仍不清时输出 `[SCHEMA-SELECTION-BLOCKED]`。
+
 ## Schema Rationale 必须说明
 
 - 为什么选择该 schema。
+- 还评估了哪些 schema，为什么没有选它们。
 - 如果不是 `aisee-app-spec-driven`，为什么不需要 SRS / UI Content / Architecture 追踪。
 - 需要哪些 upstream docs：SRS / UI Content / Design Spec / Design Assets / Architecture / Issue / PR / none。
 - 是否需要 `source-map.md` seed；只有 schema 生成 `source-map.md` 时才要求 seed。