設計規約を統合する npm run verify と policy catalog を導入する

[koh110]

背景

現在、lint / test / build / custom checker / CI workflow が分散している。

AGENTS.md では変更 package に対応する CI workflow のコマンドを確認して実行することを要求しているが、Agent / 人間の双方にとって「repository が設計規約込みで正しい」ことを確認する canonical command が欲しい。

目的

機械検査を npm run verify に統合し、自然言語規約と executable policy の関係を明確にする。

実装案

root に以下のような入口を作る。

npm run verify

内部で必要に応じて以下を実行する。

• format check
• lint
• typecheck
• architecture check
• filesystem / structure check
• API contract check
• env contract check
• workflow check
• tests

また、機械規約に stable ID を持たせる。

例:

ARCH-001 package isolation
TASK-001 one-task-one-directory
TASK-002 lazy task import
DB-001   no-write-in-loop
DB-002   no-find-first
TEST-001 no-describe
API-001  typed-validator
ENV-001  env-only-in-config
CI-001   dependency-trigger

AGENTS.md の役割

最終的に以下へ寄せる。

• machine-readable policy = rule
• AGENTS.md = rationale / exception / design philosophy

将来的には AGENTS.md に「禁止」「必ず」「〜に限る」等の normative rule を追加する場合、policy ID または human-only annotation を要求する meta-check も検討する。

Acceptance Criteria

• root に canonical な npm run verify がある
• CI とローカルで同じ verification entrypoint を利用できる
• custom policy に stable ID を付与する
• policy ID と実装 checker の対応を一覧化する
• AGENTS.md から機械判定可能な詳細ルールを削減する
• 新しい自然言語 rule が無制限に増えない運用を定義する

追加: natural-language policy coverage checker

これは将来検討ではなく、Policy as Code を維持するための実装対象とする。

AGENTS.md / agents/*.md に新しい normative rule が自然言語だけで追加されると、時間とともに再び「ドキュメントを正しく読めること」が前提になってしまう。

そのため、規約文に以下のどちらかを要求する。

• executable policy の stable ID
• 機械化しない理由を示す human-only annotation

例:

- [ARCH-003] shared から runtime package を import しない

または:

<!-- policy: human-only -->
- 共通化を提案する前に、framework が変わっても成立するか検討する

checker の対象候補

日本語・英語の normative wording を heuristic に検出する。

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

完全な自然言語理解を目指さず、「新しい強い規約が policy catalog から漏れること」を検出する safety net とする。

Acceptance Criteria 追加

• normative rule に policy ID または human-only annotation を要求する
• AGENTS.md / agents/*.md を checker 対象にする
• checker 自身の正常系・異常系 fixture がある
• policy catalog に存在しない policy ID を検出する
• executable policy 側に存在するが docs から参照されない orphan policy も可能なら検出する

Policy coverage checker の実装 issue

natural-language policy coverage の具体実装は以下で追跡する。

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

この issue (#38) では policy catalog と npm run verify への統合を担当する。