自然言語の設計規約と executable policy の coverage を検査する

[koh110]

背景

機械判定可能な既存規約を一度 lint / checker に移しても、その後 AGENTS.md / agents/*.md に新しい禁止事項や必須事項が自然言語だけで追加されれば、再びドキュメント依存へ戻る。

Policy as Code の導入だけでなく、その状態を維持する仕組みが必要。

目的

自然言語で追加された normative rule と executable policy catalog の対応関係を CI で検査する。

方針

規約には原則として以下のどちらかを要求する。

Executable policy

- [DB-004] migration 内で seed INSERT を行わない

Human-only rule

<!-- policy: human-only -->
- 共通化を提案する前に本質的な共通性があるか検討する

checker

以下のような normative wording を heuristic に検出する。

• 必ず
• 禁止
• 〜しない
• 〜に限る
• must
• never
• required

検出した文に policy ID / human-only annotation が無ければ warning / error にする。

また policy catalog との双方向整合も検査する。

• docs が未知の policy ID を参照していないか
• executable policy が catalog に登録されているか
• catalog entry に実装 checker が存在するか
• orphaned policy を検出できるか

注意

自然言語解析の完全性は求めない。

目的は semantic lint ではなく「強い規約を雑に追加すると CI が気づく」safety net を作ること。

Acceptance Criteria

• normative rule の未登録を検出できる
• policy ID と catalog の整合性を検査できる
• human-only annotation を正式な escape hatch として定義する
• checker の fixture がある
• npm run verify に統合する