設計規約を自然言語から静的解析・Policy as Code へ移行する

[koh110]

目的

AGENTS.md / agents/*.md に自然言語で記述されている設計規約のうち、機械的に判定可能なものを lint / checker / schema validation / dependency analysis へ移行する。

目標は、

Agent がドキュメントを正しく読んだことを前提にしない repository

にすること。

方針

• 機械判定可能な規約は executable policy にする
• 自然言語には rationale / trade-off / exception を残す
• AST lint に向かないものは filesystem checker / dependency checker / schema validation を利用する
• 誤検知しやすい意味的規約を無理に error 化しない
• 新規 checker は warn → 既存違反修正 → error の順で導入する

Sub issues

• task の構造・遅延 import 規約を静的検査する #29
• monorepo の package 境界・依存方向を静的検査する #30
• Prisma / DB アクセス規約を静的検査する #31
• Testing Guidelines の機械判定可能な規約を lint 化する #32
• React / TypeScript の機械判定可能な設計規約を lint 化する #33
• OpenAPI / handler / route の契約整合性を静的検査する #34
• 環境変数を schema 化し .env.sample / runtime 設定との整合性を検査する #35
• package dependency graph と GitHub Actions の path filter を整合させる #36
• actionlint / zizmor / Knip を repository 静的解析へ追加する #37
• 設計規約を統合する npm run verify と policy catalog を導入する #38

完了条件

• 機械判定可能な重要規約が自然言語だけに存在しない
• repository architecture の主要 invariant が CI で検証される
• npm run verify でローカルでも同じ検査を実行できる
• AGENTS.md が implementation rule の羅列ではなく rationale 中心になっている

Additional sub issues

初期整理後に追加で抽出した architecture / runtime / meta-policy の静的解析。

• client の API 通信・Server Action 境界を静的検査する #40
• package 内の layer / directory architecture を静的検査する #41
• Docker / Compose / worktree の runtime invariant を静的検査する #42
• 自然言語の設計規約と executable policy の coverage を検査する #43

既存 sub issue 側にも以下を追加済み。

• Prisma / DB アクセス規約を静的検査する #31: destructive migration checker
• React / TypeScript の機械判定可能な設計規約を lint 化する #33: React Hook Form rules
• actionlint / zizmor / Knip を repository 静的解析へ追加する #37: shellcheck / hadolint / secret scanning
• 設計規約を統合する npm run verify と policy catalog を導入する #38: natural-language policy coverage と policy catalog の統合

Final coverage sub issues

repository 全体の暗黙 contract を追加調査して抽出した quality / toolchain / security の検査。

• 全 workspace の quality gate / CI coverage を静的検査する #44
• Node / npm / TypeScript toolchain version の整合性を静的検査する #45
• local/test 専用 security stub の fail-closed を機械保証する #46

既存 issue 側にも以下を追加済み。

• monorepo の package 境界・依存方向を静的検査する #30: package public API / generated code boundary
• 環境変数を schema 化し .env.sample / runtime 設定との整合性を検査する #35: client-visible env / server-only env boundary
• client の API 通信・Server Action 境界を静的検査する #40: *.server.* / server-only dependency boundary
• Docker / Compose / worktree の runtime invariant を静的検査する #42: init idempotency / cleanup isolation / nginx dynamic-port contract

Security / policy hardening sub issues

Policy as Code の bypass 防止と browser/backend security boundary を追加で検査する。

• lint / policy suppression の利用を静的検査する #47
• browser session / API proxy の security invariant を機械保証する #48
• structured logging / sensitive data redaction を静的検査する #49

既存 issue 側にも以下を追加済み。

• OpenAPI / handler / route の契約整合性を静的検査する #34: API auth contract と authorization middleware の整合
• package dependency graph と GitHub Actions の path filter を整合させる #36: package-lock / .npmrc 等 repository-wide CI input coverage
• client の API 通信・Server Action 境界を静的検査する #40: GET を method ではなく execution context で分類する data-access architecture
• Docker / Compose / worktree の runtime invariant を静的検査する #42: graceful shutdown contract