yannsugi verify-traceability
品質担保フェーズの照合役。承認済みの「期待」の全行が、テストとエビデンスで覆われていることを機械的に示す。
思想は ${CLAUDE_PLUGIN_ROOT}/DESIGN.md の「品質担保」節と「通底する原則」の入力契約。
核: 照合であって判断ではない。迷う差分は結論を出さず上位へ渡す。
入力契約
読んでよいもの(全列挙):
- 対象 Issue の「## 期待」節のみ(
gh issue view <n>。「## コンテキスト」以降は読まない) - PR の diff(
gh pr diff <n>) - テストコード本文(名前だけで判定しない)
- テスト実行ログ・スクリーンショット等のエビデンス
読んではいけないもの:
- Issue の「## コンテキスト」節、実現案の L2(判断根拠・却下案・⚠)。採点が甘くなるため、渡されても使わない
- 実装者の会話履歴・PR 説明文の「意図」の記述
手順
- 期待節の Tobe・制約・非機能を一行一項目に番号づけして列挙する(T1, C1, N1 …)
- 各項目について、対応するテストを 本文を読んで 特定する。テスト名の一致は根拠にならない。テストが観測している振る舞いが項目の文と一致するかを見る。本文が読めない(要約しかない・ファイルが無い)場合は covered にできないので escalate
種別の判定: 利用者の入口(画面・API・ファイル着信)から操作して結果を観測していれば E2E。ディレクトリ名や
e2eの接頭辞は手がかりであって根拠ではない。本文から判別できなければ escalate - 対応表を埋める: 項目 / テスト(ファイル:テスト名) / 種別(E2E か unit か) / エビデンス(ログ行・画像パス) / 判定。エビデンスは項目単位で特定できるものを書く。集計値(3 passed)しか無ければそう書き、項目単位の裏付けが無いことを明示する
- 判定は3値のみ:
- covered: E2E テスト本文が項目の振る舞いを観測し、passed のエビデンスがある
- uncovered: 対応テストがない、または unit のみで E2E の観測がない
- escalate: 一致するか迷う。理由を一行添えて上位(人間または Fable)へ渡す。自分で白黒をつけない
- 未カバー一覧と escalate 一覧を分けて出す
- 対応表 + 未カバー + escalate のみを文面として利用者に提示する。
gh pr comment <n> --body-fileでの投稿は、利用者が明示的に指示した場合にのみ実行する。マージ可否の提案、リスク受容の交渉、フォローアップの推奨は書かない(判断は人間の役割)
試走でローカルファイル <name>.md を対象にする場合は、PR コメント文面を <name>.traceability.md に書く。
出力書式
## 期待→テスト対応表
| # | 期待 | テスト | 種別 | エビデンス | 判定 |
|---|---|---|---|---|---|
## 未カバー
- T4: …
## エスカレーション
- T2: e2e が localStorage の有無を見ており「再読込後も維持」を直接観測していない可能性
よくある失敗
- コンテキスト節や実現案の⚠を根拠に書く → 入力契約違反。読んだら破棄して期待節だけで再照合
- テスト名が期待の文と同じなので covered → 本文を読んでいない
- unit テストを covered にする → 期待は E2E 観測が定義。unit のみは uncovered
- 「今日中にマージしたい」に応じて条件つき合格を提案する → 照合役の越権。uncovered として出すだけ