背景

大型 repo 同時有很多 changes / specs 時，完整 validation log 很長，reviewer 真正想看的通常只有 warning 與 error。v1.12.0 提供 findings-only report，讓「人看的輸出」與「CI 的成功失敗判定」分離。

GitHub Actions 範例

name: OpenSpec validation
on:
  pull_request:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g @fission-ai/[email protected]
      - name: Validate OpenSpec and show findings only
        run: openspec validate --all --report findings

故意製造一個 warning

假設某個 archived capability 的 Purpose 還保留佔位文字，CI 會顯示該 finding；成功的其他 specs 不會佔滿 log。

關鍵是：如果 validation 規則判定失敗，job 仍會因原本的 exit code 失敗。--report findings 不會把紅燈洗成綠燈。

何時不要用

本機第一次整理大量規格時，完整報告仍較適合，因為你可能想確認哪些項目已通過。Findings-only 更適合已穩定運作的 CI 與 review 階段。

關鍵學習點

• 報告格式與驗證語意是兩件事。
• CI 應讓 reviewer 快速看到需要處理的內容。
• 不要用「少輸出」來掩蓋失敗；exit code 才是 automation contract。