校验报错了怎么办

提交 / commit / CI 的时候，14 个 Validator 会自动跑。本地跑挂了，CI 一定挂；CI 跑挂了，本地一定也能复现。

本页是错误码字典：看到啥报错查哪一行。

第一步：先跑一下看看

./scripts/aiko-validate.sh         # 普通模式
./scripts/aiko-validate.sh --strict # 严格模式 (0 ERROR 0 WARNING 才过)

第二步：让 AI 替你修

不想手动改？调 /aiko-validate-and-fix <change-name>：

> /aiko-validate-and-fix add-coupon-discount

跑 aiko-validate.sh --strict
✗ ERROR: matrix.required_missing acceptance.md not found
✗ ERROR: trace.broken_ref ACC-007 -> REQ-FN-099 (not found)
⚠ WARNING: glossary-usage.unused GLOSS-payment-method

自动修复...
✓ 已建 acceptance.md 骨架,请补内容
✓ ACC-007 改引用 REQ-FN-007 (按相似度推断)
✓ glossary 未引用项标记 INFO,可忽略

还剩 1 ERROR (acceptance.md 内容待补)

AI 处理不了的会停下来告诉你。

错误码速查（按出错频率排）

matrix.required_missing

啥意思：你选的档位要求写这件文档，但你没写。

怎么办：

• 补上这个文件（看 每件文档怎么写）
• 或者降档：去 .openspec.yaml 把 change-type: m 改成 s（如果合理的话）
• 或者升档不可降，按矩阵补足

matrix.over-spec

啥意思：这个档位本不需要这件文档，你写了。

怎么办：

• 删掉这件文档
• 或者升档：你写了说明真的要这件，把 change-type 提一档

trace.broken_ref

啥意思：你写了一个 ID 引用（比如 satisfies: REQ-FN-099），但目标 ID 不存在。

怎么办：

• 检查拼写（最常见就是手抖打错数字）
• 去主笔文档（这里是 requirements.md）补一条 REQ-FN-099
• 或者改成正确的 ID

id-uniqueness.duplicate

啥意思：同一个 change 里某个 ID 用了两次。

怎么办：改一个。可能你 copy-paste 忘改了序号。

entity-schema.missing_required_field

啥意思：某条 yaml 块缺了必填字段。

例：

- id: ACC-007
  title: 满减券生效
  # 缺 satisfies (tier=core, required)

怎么办：补字段。如果你不知道有哪些必填，看 openspec/schemas/<lane>/entities/<artifact>.yaml。

ssot.duplicate_requirement

啥意思：同一条事实在两个文档里写了。比如 requirements.md 写了 用户必须能用手机号登录，vision.md 又重复了一遍。

怎么办：删一份。下游想引用，用 ID 引（看 为什么不要复制粘贴）。

ssot.misplaced_*

啥意思：事实写错地方了。

• ssot.misplaced_requirement：在 vision.md 里写了功能能力 → 应该归 requirements.md
• ssot.misplaced_nfr：在 requirements.md 里写了 NFR 数字 → 归 nfr.md
• ssot.misplaced_test_step：在 acceptance.md 里写了测试步骤 → 归 test-cases.md
• ssot.misplaced_task：在 adr.md 里写了普通任务 → 归 tasks.md

怎么办：把那段话搬到对的文档去。

scenario-quality.missing_gwt

啥意思：spec 里的 Scenario 缺 Given / When / Then。

怎么办：补完 GWT 三段。模板：

### Scenario: 标题
  Given 前置条件
  And 另一条前置
  When 触发动作
  Then 期望结果
  And 另一条期望

nfr-acceptance-coverage.missing_acc

啥意思：你在 nfr.md 写了一条非功能需求，但没有 acceptance 条件引用它，没法验。

怎么办：去 acceptance.md 补一条引用这个 REQ-NFR-*。

dev-coverage.missing_in_spec

啥意思：PD 写了一条 REQ-FN-007，但开发包的 specs/ 里没人引用、没人实现。

怎么办：

• 在 specs/<capability>.md 加一条 Requirement 引用 REQ-FN-007
• 或者评审决定这条这次不做 → 加到 review-log.md 留痕

pipeline-gate.tasks_mismatch

啥意思：tasks.md 里某段都勾完了，但 aiko.pipeline 节点还卡在前一段。

怎么办：

./scripts/pipeline/advance-node.sh --change <name> --to <next-node>

pipeline-gate.node_skip

啥意思：你尝试从 impl 直接跳到 e2e_run，跳过了 tdd 和 e2e_gen。

怎么办：回到 tdd 跑完单测，再 e2e_gen 生成脚本，再 e2e_run。不能跳。

ai-constraints.missing_fallback

啥意思：你声明了一个 AI 能力（在 ai-spec.md），但没写 fallback 策略。

怎么办：在 ai-spec.md 里加 GUARD-* 字段，明确 LLM 不可用时的降级路径。

perf-budget.invalid_metric

啥意思：性能指标五字段不全或方向不对。

怎么办：每条 NFR 性能指标必须有 metric / target / op / unit / measured_at 五字段，比如：

- id: REQ-NFR-PERF-003
  metric: p99_latency
  target: 100
  op: "<="
  unit: ms
  measured_at: at peak hour

language.invalid_utf8

啥意思：文件里有不规范的 UTF-8 字符（通常是从 Word / PDF 粘贴带来的）。

怎么办：

# 自动转 NFC
python3 -c "import unicodedata,sys; sys.stdout.write(unicodedata.normalize('NFC', open(sys.argv[1]).read()))" file.md > tmp && mv tmp file.md

或者让 /aiko-validate-and-fix 替你跑。

glossary-usage.unused（INFO 级，不阻断）

啥意思：你在 glossary.md 定义了 GLOSS-xxx 但下游没引用。

怎么办：可以忽略。可能是定义早了/留给后续 change 引用。

调试技巧

只跑某几个 Validator（本地调试用）：

AIKO_VALIDATORS=matrix,trace ./scripts/aiko-validate.sh

看完整 Validator 列表：

./scripts/aiko-validate.sh --list

看某条规则的 source：

cat tools/openspec-aiko/src/aiko/validators/<name>.ts

校验在哪些时刻跑

本地与远端跑同一套，没有 || true 绕过。所以本地能过 = CI 一定能过（除非 CI 跑了 L3，本地不跑）。

装本地 pre-commit hook

pip install -r requirements-dev.txt
./scripts/install-pre-commit-hook.sh

之后每次 commit 自动跑。别用 --no-verify 绕，CI 一样会拦你。

关联

• 怎么选档
• 每件文档怎么写
• 为什么不要复制粘贴 (SSoT)
• 推进开发任务到 ready