sumsub-conformance

Sumsub — 適合性（規制 ↔ デプロイ済み設定）

規制の各要件をライブ設定グラフ全体で追跡し、要件ごとに「収集されているか？ → スコアリングされているか？ → 適用されているか？」に回答します。ほかの何ものも明らかにしない主な調査結果は、収集済み・未適用です。つまり、設定が規制で必要とされるデータを収集してスコアリングしているにもかかわらず、それに基づいて動作していません（例：スコアリングされているものの、その後の処理に振り分けられない適合性アンケート）。

これはコンプライアンスを保証するものではなく、ギャップを助言するアシスタントです。 設定で表現できる部分を決定論的に検証し、それ以外は正直に対象外として扱います（意味上の意図＝判断が必要、SDK／プラットフォームの結果＝対象外）。人間による承認を得てください。

使用するタイミング

• 既存のクライアント：「こちらが規制、こちらがテナントです。実際に適用されているのは何ですか？」
• create-* スキルを使って Sumsub を設定した新規クライアント：生成 → 検証のループを完了します。構成した設定は、元となる規制を最終的に適用していますか？

エンドポイント（読み取り専用）

すべて scripts/sumsub_curl.sh（App-Token HMAC）経由で実行します。resolve_graph.sh がこれらをラップします：

目的	メソッド + パス
レベル（対象を特定）	GET /resources/applicants/-/levels
ワークフロー（レベルを参照するものを自動検索）	GET /resources/api/applicantWorkflows + GET /resources/api/applicantWorkflows/{id}
アンケートの内容 + スコア	GET /resources/api/questionnaires/{id}
PoA／クロスチェックのプリセット	GET /resources/api/poaStepSettings/{id} · GET /resources/api/crossCheckPresets/{id}
エンタイトルメント（allowedChecks キー）	GET /resources/api/agent/settings/bgCheckTargets

認証 — App Token + シークレット（サンドボックスのみ）

このスキルは公開 Sumsub API にアクセスし、 認証リファレンスに従って各リクエストに署名します。仕組みの説明は sumsub-api-auth にあります。

⚠️ サンドボックスのトークンのみ。 読み取り専用ですが、それでも本番環境の App Token は受け付けないでください。ユーザーから提示された場合は拒否し、 https://cockpit.sumsub.com/checkus/home?sbx=true からサンドボックス用のペアを取得するよう依頼してください（Connect Sumsub to your AI agent → Build & configure → Generate token）。ヘルパーは sbx: で始まらないトークンを拒否します。

変数	例
SUMSUB_APP_TOKEN	sbx:...
SUMSUB_SECRET_KEY	対応するシークレット
SUMSUB_BASE / SUMSUB_ENV=dev	任意。dev は dev-api.sumsub.com（内部）を対象にします。

手順

スクリプトを使ってください。決定論的な手順を手作業で実装しないでください。 このスキルの要点は、解決と判定が決定論的であり、実行のたびに目視で導き直す必要がないことです。

• グラフの解決には、必ず resolve_graph.sh だけを使ってください。 /resources/... エンドポイントを直接呼び出したり、レベルを手作業で列挙したり、HTTP <code> の末尾部分を自分で取り除いたりしないでください。これらはすべてスクリプトが行い、整理されたグラフを出力します。
• グラフを解決できない場合は、そこで停止してください。失敗を回避して処理を続けてはいけません。 resolve_graph.sh が 401／403、404、または 0 levels／「level not found」を返した場合、実行を続けることはできません。失敗の内容（無効なサンドボックス用トークンまたは誤ったレベル名が原因の可能性があります）を明確に報告して、停止してください。エラーを回避するために resolve_graph.sh（または他のスクリプト）を編集したり、ID によるフォールバックを追加したり、別のエンドポイントを再試行したり、その他の方法でグラフを独自に作成したりしないでください。また、不完全なグラフや代替グラフから、レポート、バケット数、または CONFORMANT 判定を出してはいけません。解決済みのグラフがなければ、指摘事項もありません。
• 判定は、必ず trace.py／report.py の結果から導き出してください。 ワークフロー／質問票の JSON を目視で読んで「適用済み／未適用」を独自に判断しないでください。そうすると、ばらつきや幻覚が再び入り込みます。COLLECTED-NOT-ENFORCED の指摘事項はエンジンから出力される必要があります。
• スクリプトがすでに実行されている場合は、その出力を信頼してください。手動の API 呼び出しで再検証しないでください。
• マップの手順でグラフを確認するには、python3 scripts/graph_summary.py "$CONFIG" を実行してください。 グラフ JSON を手作業で順に調べないでください。questionnaires／poaPresets／crossCheckPresets は ID をキーとする辞書です（反復すると ID 文字列が返され、'str' has no attribute 'get' が発生します）。一方、entitlements は リストです。graph_summary.py は必要なセクション／項目のインデックスとスコアを正しく出力します。 エージェントの判断が必要なのは、規制を読み込む「読み込み」と、要件をデプロイ済みの設定要素（質問、docSets、フィールド、国、entitlements）に対応付ける「マップ」の2つの手順だけです。それ以外はすべてスクリプトで処理します。

成果物 — 保存先と命名規則は必須です。 実行のたびに、成果物はすべて元の規制文書ファイルと同じディレクトリに、その拡張子を除いたファイル名を基にした名前で保存する必要があります。カレントディレクトリや独自の名前で保存しないでください。正確なパスを最初に一度だけ導出してください。

eval "$(python3 scripts/artifact_paths.py "<path/to/RegFile.pdf>")"
#  $REQUIREMENTS = <dir>/<stem>_regulations.json   (手順1と3で作成する要件)
#  $CONFIG       = <dir>/<stem>_config.json         (手順2の resolve_graph 出力)
#  $REPORT       = <dir>/<stem>_report.md           (手順6で生成するレポート)

例：Level4regulations.pdf → Level4regulations_regulations.json、Level4regulations_config.json、Level4regulations_report.md。以下の手順では、$REQUIREMENTS／$CONFIG／$REPORT をそのまま使用してください。

1. 規制を取り込みます（判断が必要です）。Read ツールでドキュメントを読むだけで構いません。このツールは PDF をネイティブに読み取り（ページをレンダリングし、テキストを抽出する）ため、インストールは不要です。 約 10 ページを超える PDF は、ページ範囲を指定して読み取ります（Read ツールの pages パラメーターを使用し、1 回の呼び出しにつき最大 20 ページ）。目視での読み取りは、テキスト抽出ツールと同等以上です。テキストのみの抽出では失われる表、見出し、レイアウトが保持されます。任意。ただし、すでにインストール済みの場合に限り、妨げにならない範囲で使用します： pypdf／pdftotext を使えば、テキスト主体の長い PDF を一度に取り込めます。また、scripts/render_regulation.py（PyMuPDF）は、スキャンされた画像のみの PDF を PNG に事前レンダリングして、DPI を明示的に制御できます。詳細は references/conformance-method.md のステップ 1 を参照してください。ライブラリがない場合は、PDF を Read で直接読み取ってください。 次に、要件を抽出して $REQUIREMENTS（ソースと同じ場所にある <stem>_regulations.json。上記の成果物ルールを参照）に書き込みます。形式は references/requirements-schema.md に従います。各要件は {id, source, text, type, enforceable, …} です。必ず source を記録してください。これは元のドキュメント内の引用箇所（セクション番号／見出し／ページ。例："§5.9.2"、"Section 2 — Scoring Result"、"p.21"）です。レポートではこれを先頭に示し、検出結果を人為的な ID ではなく規制にたどれるようにします。SDK／プラットフォーム／CRM に属する結果には enforceable: sdk|platform を設定します。 抽出した要件をユーザーに提示し、トレースを始める前に確認を得てください。ここが最もリスクの高いステップです。
2. デプロイ済みグラフを解決します（決定論的）。bash scripts/resolve_graph.sh <levelNameOrId> > "$CONFIG" （レベル、スコア付き質問票、プリセット、自動検出されたワークフロー、エンタイトルメント）。この 1 つのコマンドで、手動によるレベル一覧の取得／curl／HTTP トレーラーの除去はすべて置き換えられます。手作業で行わないでください。
3. マッピングします（判断が必要です）。まずグラフを確認します：python3 scripts/graph_summary.py "$CONFIG"。このコマンドは、[section]/[item] インデックスと選択肢のスコアを含む質問票、docSets、APPLICANT_DATA フィールド、geo、エンタイトルメント、ワークフローを出力します（JSON を手作業で順に確認しないでください）。次に、各要件に適切な type を選び、match を設定します。すべてが質問票の質問とは限りません。 match の型ごとの形式は references/requirements-schema.md に記載されています。
   • 質問票の質問／スコア → match: {questionnaire, section, item}（および expectScores）；
   • 収集済みドキュメント → match: {docSet: "IDENTITY", types: [...]}；
   • 申請者データフィールドの有無 → type: data-field、match: {field: "dob"}／{fields: [...]}；
   • 国の許可リスト／禁止管轄区域 → type: country-eligibility、match: {mustHaveAllowlist: true}／{mustExclude: [...]}；
   • セルフィーのライブネス → type: liveness、match: {}；
   • プロビジョニング済みの機能 → type: entitlement、match: {entitlement: "WATCHLISTS"}；
   • スクリーニング／ルーティングの結果 → 識別力のある enforcementSignal を設定します（汎用トークンは使用しないでください）。 慎重に判断してください。対象が存在するか不明な場合は、推測するのではなく match: null（→ MISSING）にします。
4. トレースします（決定論的）。python3 scripts/trace.py --requirements "$REQUIREMENTS" --graph "$CONFIG" → 検出結果を MISSING / SCORING-MISMATCH / COLLECTED-NOT-ENFORCED / NOT-CONFIG-REPRESENTABLE / CONFORMANT に分類し、それぞれに証拠と basis（決定論的か判断に基づくか）を付けます。分類の判定はここで行われます。ワークフロー JSON を読んで「適用済み／未適用」を自分で判断しないでください。
5. （任意）衛生チェックのサブパス。 同じグラフを同梱のリンターに渡して、適合性とあわせて、気づきにくい設定ミス（エンタイトルメントの不足、参照先のないプリセット／質問票、非推奨の SDK、無効な AML プロバイダー）を検出します。エンタイトルメントはグラフから直接読み取られます： bash scripts/resolve_graph.sh <level> | python3 scripts/lint_config.py。ルール一覧は references/lint-rules.md を参照してください（references/rules.json から生成）。
6. レポートを作成します。正式なフォーマッターで $REPORT に出力し、手動で書式を整えないでください。 書式は固定されており、毎回同じ形式になります： python3 scripts/trace.py --requirements "$REQUIREMENTS" --graph "$CONFIG" | python3 scripts/report.py --date <today> > "$REPORT" → ステータスの見出し、固定形式の分類別件数テーブル、固定順にまとめられた検出結果（それぞれに証拠と basis を記載）、固定の注意事項フッターを含む Markdown が出力されます。$REPORT をそのまま提示してください。文章で再要約しないでください。過去の実行結果に差が生じた原因はそれでした。（ツールで使用するもう 1 つの正式な形式は trace.py の JSON です。機械処理で必要な場合は、ほかのファイルと一緒に保存してください。）

このツールが行わないこと

• コンプライアンスを保証するものでも、コンプライアンス担当者に代わるものでもありません。
• 存在の有無、スコア、ルーティングの強制を超えて、意味上の正しさを検証するものではありません （たとえば、質問の文言が法的に適切かどうかは判断が必要です）。
• SDK／プラットフォーム／CRMの結果（開示ポップアップ、デモアカウント、読み取り専用モード、 25%／10%の制限、CRMのタイムスタンプ）は検証できません。これらは NOT-CONFIG-REPRESENTABLE に分類されます。

ガードレール

• 決定論的な事実と判断を分けてください（basis フィールド）。マッピングの推測を 検証済みの所見として示してはいけません。
• トレースの対象は要件からデプロイメントまでのみです。デプロイ済みの質問に「余計な質問」という フラグを付けることはありません（誤検知の分類を回避します）。余分な質問を報告する場合は、明示的な アドバイザリーノートとして記載してください。
• enforcementSignal は識別力のある値でなければなりません。一般的なトークン（country）は すべてに該当するエッジに一致し、誤って CONFORMANT になります。詳細は references/requirements-schema.md を参照してください。
• 解決に失敗した場合は正直に失敗してください。回避策を使ってはいけません。 resolve_graph.sh が認証 エラー／404／0 levels を返した場合は、停止してその旨を報告してください。回避するためにスクリプトを 編集したり、不完全なグラフからレポートを捏造したりしてはいけません（Procedure の囲みを参照）。

関連項目

• references/requirements-schema.md — 要件モデルと分類。
• references/conformance-method.md — 5つの手順、ガードレール、対象範囲。
• references/lint-rules.md — 同梱の衛生状態チェックルールカタログ（サブパス）。
• sumsub-analyze-regulation — 逆方向（規制からビルド計画へ）。

実例（examples/）

• sample-requirements.json + sample-graph.json — すべての分類を網羅する合成データ（test_trace.py を実行）。
• fiu-india-vasp-mapped.json + vasp-graph.json — 仮想のVASPレベルにマッピングされた幅広いAMLガイドライン。 自己完結型で、オフラインで両方をまとめてトレースできます： python3 scripts/trace.py --requirements examples/fiu-india-vasp-mapped.json --graph examples/vasp-graph.json | python3 scripts/report.py。
• cfd-requirements.json — 実際のCFD／MiFID要件（稼働中の cfd-onboarding-eu グラフに対して実行）。
• fiu-india-requirements.json — マッピング前の、幅広いガイドラインに対する取り込み段階の出力。
• audit-input{,-dirty}.json — 衛生状態リンターのテスト用データ（test_lint.py を実行）。