背景
@d-zero/page-cluster に onClusterReason が追加された（d-zero-dev/tools#927、現在レビュー待ち・CI green）。クラスタが確定するたびに1回、そのクラスタの選定理由を構造化データ（ClusterReason）として通知するコールバック。
type ClusterReason = {
memberCount: number;
blocking: { blockKey: string; reason: BlockingReason }[]; // css共有stylesheet集合 or URLパスプレフィックス
structuralCoreTokens: string[]; // クラスタ内で共有されているDOM構造トークンの多数決コア
landmarks: {
[type in 'header'|'footer'|'nav'|'aside'|'form'|'search']?: {
presenceRate: number; // このクラスタの何割のページがこのlandmarkを持つか
chromeRate: number; // そのうち何割がサイト共通chromeと判定されたか
shellTokens: string[]; // chrome判定の根拠トークン集合
memberCountWithInstance: number;
};
};
siblingClusterKeys: string[]; // 同一ブロッキンググループ内で分岐した兄弟クラスタのキー
};同時に、includeLandmarkPositions オプション・PageClusterKeyResult・PageLandmarkReport 型は削除された（本番未使用のため後方互換なし）。
即座に必要な対応: なし
nitpicker側のコードを全数確認した結果、includeLandmarkPositions／PageClusterKeyResult／PageLandmarkReport への参照はゼロ件。classify-page-templates.ts は resolvePageClusterKeys(factory, { onProgress }) のみを呼んでおり、削除されたAPIは使っていないため、型エラー・実行時エラーは発生しない。
また @nitpicker/core/package.json の依存は "@d-zero/page-cluster": "0.3.1" と完全固定（range指定なし）で、.yarnrc.yml の npmMinimalAgeGate: 7d もあるため、npm公開後もこちらで明示的にバージョンを上げるまで何も変わらない。
本来やりたいこと: templateKey に選定理由を紐付ける
現状 page_templates テーブル（packages/@nitpicker/crawler/src/archive/create-adjunct-tables.ts）は template_key（string）のみを保持し、理由に相当するデータは一切持たない。packages/@nitpicker/query/src/compute-css-intersection.ts の冒頭コメントは「page-clusterが内部で使っているCSS絞り込みロジック（頻出hrefの除去・first-partyフィルタ）が将来public API化されたら統合を検討する」と事前に予告している——onClusterReason はまさにこの予告に応えるものと言える。
統合する場合に触る箇所（現状把握のみ、設計は未着手）:
- DBスキーマ:
create-adjunct-tables.ts の page_templates（列追加 or 新規テーブル）
- 書き込みAPI:
replace-page-templates.ts（現状 Map<url, templateKey> のみ受け取る形）
- 分類実行:
classify-page-templates.ts:93-96（resolvePageClusterKeys 呼び出しに onClusterReason を渡す）
- クエリ集計層:
list-page-template-clusters.ts / TemplateClusterSummary 型（compute-css-intersection.ts 等の自前簡易実装を ClusterReason.blocking/structuralCoreTokens で置き換えられる可能性）
- APIレイヤー:
register-template-clusters-route.ts、template-clusters-cache.ts
- フロントエンドUI:
template-clusters-view.tsx（clusterHeading()）、use-template-clusters.ts、translations.ts
決定済みの設計判断（tools側の議論より）
- 理由は構造化データのみ。人間可読な文言（「ヘッダーが共通です」等）は返さない — page-clusterは表示・言語非依存を維持する設計方針のため、文言組み立てはnitpicker側の責務
- コールバックはクラスタ単位（ページ単位ではない）。
ClusterReason はクラスタ数に比例したサイズなので、ページ数の上限を受けない（旧 includeLandmarkPositions が20,000ページ制限を持っていたのはページ単位設計が原因だった）
- landmarkの位置情報そのものが必要な場合は、
extractLandmarks（既存公開API）と新規公開された isChromeLandmarkInstance・jaccardSimilarity（@d-zero/page-cluster/is-chrome-landmark-instance・@d-zero/page-cluster/jaccard-similarity）を呼び出し側が組み合わせる設計
参照
背景
@d-zero/page-clusterにonClusterReasonが追加された（d-zero-dev/tools#927、現在レビュー待ち・CI green）。クラスタが確定するたびに1回、そのクラスタの選定理由を構造化データ（ClusterReason）として通知するコールバック。同時に、
includeLandmarkPositionsオプション・PageClusterKeyResult・PageLandmarkReport型は削除された（本番未使用のため後方互換なし）。即座に必要な対応: なし
nitpicker側のコードを全数確認した結果、
includeLandmarkPositions／PageClusterKeyResult／PageLandmarkReportへの参照はゼロ件。classify-page-templates.tsはresolvePageClusterKeys(factory, { onProgress })のみを呼んでおり、削除されたAPIは使っていないため、型エラー・実行時エラーは発生しない。また
@nitpicker/core/package.jsonの依存は"@d-zero/page-cluster": "0.3.1"と完全固定（range指定なし）で、.yarnrc.ymlのnpmMinimalAgeGate: 7dもあるため、npm公開後もこちらで明示的にバージョンを上げるまで何も変わらない。本来やりたいこと:
templateKeyに選定理由を紐付ける現状
page_templatesテーブル（packages/@nitpicker/crawler/src/archive/create-adjunct-tables.ts）はtemplate_key（string）のみを保持し、理由に相当するデータは一切持たない。packages/@nitpicker/query/src/compute-css-intersection.tsの冒頭コメントは「page-clusterが内部で使っているCSS絞り込みロジック（頻出hrefの除去・first-partyフィルタ）が将来public API化されたら統合を検討する」と事前に予告している——onClusterReasonはまさにこの予告に応えるものと言える。統合する場合に触る箇所（現状把握のみ、設計は未着手）:
create-adjunct-tables.tsのpage_templates（列追加 or 新規テーブル）replace-page-templates.ts（現状Map<url, templateKey>のみ受け取る形）classify-page-templates.ts:93-96（resolvePageClusterKeys呼び出しにonClusterReasonを渡す）list-page-template-clusters.ts/TemplateClusterSummary型（compute-css-intersection.ts等の自前簡易実装をClusterReason.blocking/structuralCoreTokensで置き換えられる可能性）register-template-clusters-route.ts、template-clusters-cache.tstemplate-clusters-view.tsx（clusterHeading()）、use-template-clusters.ts、translations.ts決定済みの設計判断（tools側の議論より）
ClusterReasonはクラスタ数に比例したサイズなので、ページ数の上限を受けない（旧includeLandmarkPositionsが20,000ページ制限を持っていたのはページ単位設計が原因だった）extractLandmarks（既存公開API）と新規公開されたisChromeLandmarkInstance・jaccardSimilarity（@d-zero/page-cluster/is-chrome-landmark-instance・@d-zero/page-cluster/jaccard-similarity）を呼び出し側が組み合わせる設計参照
packages/@d-zero/page-cluster/src/build-cluster-reason.ts（@d-zero/page-cluster/build-cluster-reasonとして公開）