Bidirectional Check · 双方向検証スクリプト

四つの整合の原則は、自動で検証できて初めて拘束力を持ちます。リポジトリには scripts/bidirectional-check.py が組み込まれており、「問題 → コース」「アウトライン → 問題」「フラッシュカード被覆」の三方向を一本のコマンドにまとめています。「コースの説明が間違っている」といった意味レベルの問題は、引き続き人力での確認に頼ります（ルールは four-alignment.ja.md）。

クイックスタート

pnpm run check:alignment                          # リポジトリルートで実行。デフォルトで examples/dev-intro/ を走査
pnpm run check:alignment -- examples/my-topic/    # 指定テーマを走査

# または Python を直接実行
python3 scripts/bidirectional-check.py examples/my-topic/

終了コード：0 = すべてグリーン（△ は「軽く触れるだけ」の警告で、ブロックしない）；1 = ✗ あり（未説明／未被覆／照合不一致）；2 = テーマディレクトリが存在しない。そのまま CI／スクリプトのゲートに組み込めます。

出力サンプル（契約モード。スクリプトの実際の出力のため、中国語のまま掲載します）：

扫描主题: examples/dev-intro
  题数: 10 / 闪卡: 4 / 课程文件: ['git-basics.html', 'linux-basics.html']
  考点排布表: 4 个考点（契约模式）

方向 1 · 题 → 课
  ✓ 暂存区: 课程 14 次命中
方向 2 · 大纲 → 题（排布表对账）
  ✓ EP-01 暂存区: single×3, multi×1, judge×1 共 5 题，day D1 一致
  ✓ 闪卡数对账: 表合计 = 实际 = 4 张
方向 3 · 闪卡覆盖
  ✓ 暂存区: 闪卡已覆盖
  ○ 相对路径: 排布表声明 0 卡（了解级不配卡），跳过

结论: 全绿（△ 为略提警告，不算失败）

契約モード：出題ポイント配置表

テーマの MISSION.md に「## 考点排布表」（出題ポイント配置表）の節があると契約モードになります——出題ポイントは表から来て、内蔵キーワードは使わないため、テーマを変えてもスクリプトの書き換えは不要です：

## 考点排布表

| 考点id | 考点 | 深度 | 题型×题量 | day | 闪卡数 |
|--------|------|------|-----------|-----|--------|
| EP-01 | 暂存区 | 掌握 | single×3, multi×1, judge×1 | D1 | 1 |

考点列には中心キーワードを記入：方向 1/3 はこの語で部分文字列一致を行います（コース本文は空白を除去してカウント、カードは front / back / topic）。したがって、コースと問題文に実際に出てくる語でなければなりません。
深度：掌握 / 理解 / 了解。人力での参考情報で、機械判定には関与しません。
闪卡数 0 = アウトラインがカードなしと宣言：方向 3 はその出題ポイントをスキップします（理解レベルでよくあること）。全行のカード数の合計は、flashcards.json の実際の枚数と一致しなければなりません。

契約モードの判定ルール：

方向 1（問題 → コース）：各出題ポイントのキーワードがコース HTML（空白除去）に 3 回以上ヒットすれば被覆；1〜2 回は △ 軽く言及；0 回は ✗ 必ず補講。
方向 2（アウトライン → 問題、照合）：問題の examPoint に存在しない出題ポイント id が入っていたら ✗；未記入は △ の注意のみで、その問題は照合に加わりません（フィールド自体は必須ではないが、契約モードでは全問への記入を推奨）。各出題ポイントの実際の問題数と問題型分布は「题型×题量」列と一致しなければならず、問題の day はその出題ポイント行の day と等しくなければならず、カード数の合計も照合します。一つでも不一致なら ✗。
方向 3（フラッシュカード被覆）：カード数 1 以上の出題ポイントは、キーワードがいずれかのカードの front / back / topic にヒットしなければなりません。

フォールバックモード（配置表なし）

MISSION.md に配置表がないテーマは、高頻度語走査にフォールバックします：スクリプトは問題文と解説から内蔵キーワード（dev-intro の git/Linux の出題ポイント語）で 3 回以上出現する概念を集計し、方向 1/3 を行い、⚠ 警告を付けます。既存のテーマには影響しませんが、配置表の追加をおすすめします——フォールバックモードには方向 2 の照合がなく、出題ポイント語も dev-intro のものだからです。

いつ走らせるか

どれか一つの成果物を変更した後は必ず走らせます（詳細は four-alignment.ja.md の「いつ検証を走らせるか」）：

新しいコースを生成した後
問題の examPoint / day / 問題数を変えた後
flashcards.json を変えた後
grill CLI で一括の徹底解説を生成した後

スクリプトの限界

スクリプトがするのは粗い粒度の走査で、人力レビューの代わりにはなりません。「コースが X をまったく説いていない」「問題数がアウトラインと合わない」といった硬い穴は捕まえられますが、「コースは X を説いているが説き方を間違えている」は捕まえられず、「問題とコースが同じ語を使っているが意味が違う」も捕まえられません。最初の防衛線として使い、複雑な意味レベルの整合はテーマ作者自身の判断が必要です。

契約のブラックボックステストは apps/quiz-app/scripts/lib/bidirectional-contract.test.mjs にあります（三組の fixture テーマ：表ありで照合正しい／表なしでフォールバック／照合不一致でブロック）。pnpm test で自動的に走ります。

ソースコードはリポジトリの scripts/bidirectional-check.py を正とします。