audit-expo-skill

Clerk Expo スキルの監査

このリポジトリの skills/clerk-expo/ を、実際の @clerk/expo SDK のソースおよび参照先の clerk-docs の内容と照合します。API の形状については SDK ソースが正とし、推奨パターンについては clerk-docs が正とします。スキルはその両方に追従する必要があります。事実に関する主張（API の有無、シグネチャ、デフォルト値、バージョンの下限）で両者が食い違う場合は、常に SDK ソースを優先してください。 ドキュメントが優先されるのは、ソースでは判断できない規範的な内容（推奨するフロー、例でのプロパティの配置、ダッシュボードの前提条件）のみです。

このスキルでは、検証済みのコードスニペットを意図的にハードコードしています（鮮度ゲートを参照）。この監査は、その契約を保守するための作業です。SDK のリリース後に実行することで、スニペットが単なる伝聞にならず、検証済みの状態を保てます。

入力

• 正とする SDK ソース：packages/expo/ を含む clerk/javascript のチェックアウト（サインイン／サインアップのリソース型については packages/shared/src/types/ も含みます）。
• 正とするドキュメントソース：docs/getting-started/quickstart.expo.mdx、docs/guides/development/custom-flows/authentication/*.mdx、docs/reference/expo/** を含む clerk/clerk-docs のチェックアウト。
• 対象スキル：skills/clerk-expo/SKILL.md、references/*.md、evals/evals.json。
• 任意の照合資料：現在の API を使用する 3 つのサンプルアプリを含む clerk/clerk-expo-quickstart のチェックアウト。

ソースチェックアウトの解決

各チェックアウトは次の順序で解決してください。

1. --sdk <path>／--docs <path> が指定されている場合は、そのパスを使用します。SDK パスには packages/expo/package.json が、ドキュメントパスには docs/getting-started/quickstart.expo.mdx が含まれている必要があります。
2. このリポジトリと同じ階層にあるチェックアウトを探します。標準的な Clerk プロジェクトの配置では ../javascript と ../clerk-docs です。照合用に ../clerk-expo-quickstart も探します。
3. CLERK_JAVASCRIPT_REPO／CLERK_DOCS_REPO が設定されている場合は、そのパスを使用します。
4. チェックアウトが見つからず、ネットワークアクセスが許可される場合は、.context/ にシャロークローンします。

mkdir -p .context && cd .context
git clone --depth 1 https://github.com/clerk/javascript.git
git clone --depth 1 https://github.com/clerk/clerk-docs.git

いずれも利用できない場合は停止し、ユーザーにパスを尋ねてください。記憶やインストール済みの node_modules だけをもとに監査してはいけません。この監査は、記憶が不正確になることを防ぐために存在します。

ワークフロー

1. バージョン差分を確認する

• SKILL.md のフロントマターにあるバージョン（compatibility:）と、鮮度ゲートのテキストを確認します。
• packages/expo/package.json に記載された現在のバージョンに加え、peerDependencies（Expo SDK の範囲、React Native の下限、React の範囲）と、バンドルされたネイティブ SDK のバージョン（依存関係にある clerk-ios、clerk-android）を確認します。
• packages/expo/CHANGELOG.md から、記載されたバージョンと現在のバージョンの間の項目を確認します。これは主な作業キューです。各変更履歴項目について、スキルに影響するか、明確に無関係であるかを判定してください。

記載されたバージョンが現在のバージョンと一致し、変更履歴にも新しい内容がなければ、「差分なし」と報告して終了します。

2. SDK のサーフェスを棚卸しする

ソースから構造化された一覧を作成します（dist/ より src/ を優先してください）。

• エクスポートマップ：packages/expo/package.json の exports を確認し、すべてのサブパス（/native、/web、/token-cache、/resource-cache、/secure-store、/local-credentials、/passkeys、/google、/apple、/legacy、/experimental、…）を、追加・削除の記録とともに列挙します。
• フック：src/hooks/index.ts から再エクスポートされるすべての項目と、Expo 固有のフック（useSSO、useAuth の拡張、useSignInWithGoogle、useSignInWithApple、useLocalCredentials）を確認します。シグネチャ、戻り値の形、@deprecated タグを記録します。
• カスタムフローのリソース：packages/shared/src/types/signInFuture.ts と signUpFuture.ts にある SignInFutureResource／SignUpFutureResource のメソッドサーフェス（メソッド名、パラメーターの形、ステータス列挙型）を確認します。スキルのカスタムフローに関するリファレンスは、このサーフェスを反映しています。
• ネイティブコンポーネント：src/native/index.ts のエクスポートと、各コンポーネントの props 型（AuthView.types.ts、UserProfileView、UserButton）を確認します。スキルに記載されているが存在しなくなった prop と、新しい公開 prop を明示します。
• 設定プラグイン：src/plugin/withClerkExpo.ts を確認し、必須の環境変数、テーマオプションのスキーマ、プラットフォームに対する副作用（デプロイメントターゲット、URL スキーム）を記録します。
• プロバイダー：src/provider/ClerkProvider.tsx の props を確認し、特に実験的なもの（__experimental_passkeys、__experimental_resourceCache）と、新たに安定版となった名前を調べます。
• 開発時の警告／移行シグナル：@deprecated、console.warn、パッケージ移行のお知らせ（@clerk/expo-google-signin の分割など）を検索します。これらはスキル内の「今後の変更」に関する注記になります。

3. ドキュメントの記述内容を棚卸しする

スキルの参照先に記載されている、正規のドキュメント URL をすべて確認します。

• それぞれに対応する .mdx ファイルが、clerk-docs の該当ルートに存在することを確認します（URL パス → docs/ パス）。リンク切れは「乖離」です。
• 参照されている各カスタムフローガイドの Expo タブ／セクションと Expo クイックスタートを読み直します。ドキュメントで推奨パターンが変わっている場合（新たに必須となった手順、prop の配置変更、新しいダッシュボードの前提条件など）、スキル内の該当スニペットが引き続きコンパイルできても「乖離」とします。

4. スキルの記述内容を抽出する

SKILL.md、すべての references/*.md、evals/evals.json を読み、具体的な記述をそれぞれ抽出します。

• バージョン表記と peer dependency の範囲。
• すべてのコードスニペット（import、メソッド呼び出し、props、環境変数名）。
• API に言及するすべての条件と落とし穴（useSSO と useOAuth の違い、resourceCache と secureStore の違い、captcha のマウントポイント、treatPendingAsSignedOut の配置）。
• 機能対応表（Expo Go／dev build／web）。
• API 文字列を検証する eval の期待値。

5. 差分を取り、分類する

構造化された差分を、次の 4 つの分類で作成します。

1. スキルに不足：SDK／ドキュメントにある新しいエクスポート、フック、prop、フロー、前提条件のうち、スキルで扱うべきもの（または対象外と明示すべきもの）。
2. スキル内で古い：ソースやドキュメントと矛盾する記述（名前変更／削除された API、変更されたデフォルト値、変更された peer dependency の下限、移動した prop、無効になったドキュメント URL、古い文字列を検証する eval）。
3. スキル内で説明不足：実際の落とし穴に対する説明が不十分な記述（例：開発者が遭遇する新しいエラーコード）。
4. 詳細過多：ドキュメントやインストール済みの .d.ts のほうが詳しく説明している内容。乖離リスクを減らせる場合は、縮小案を提示します。

分類 1／2／3 の各項目について、ソースファイルと行番号、およびスキル内の修正先を記載します。

6. 編集案を提示する

修正先のファイルごとにまとめ、レビュー可能な提案を提示します。各変更には、重要度（drift、gap、または polish）、ソースの引用、修正先、統一 diff または簡潔な変更前／変更後を含めます。変更を適用する場合は、必ず次を含めてください。

• SKILL.md の compatibility: 表記と鮮度ゲートのバージョンを、監査対象の SDK バージョンに更新します。
• 期待値が変更された API を参照している場合は、eval も更新します。

正確な周辺セクションは書き換えないでください。スキルの内容を縮小する提案も可能です。

7. 適用または引き継ぎ

デフォルトでは、提案を提示してレビューを待ちます。

--apply を指定した場合は、drift と gap の編集を適用し、バージョンスタンプを更新して、polish をレビュー用に一覧表示してから検証します。検証では、JSON ファイルが解析できること、SKILL.md 内のすべての相対参照パスが解決できること、すべての正規ドキュメント URL が既存の clerk-docs ファイルに対応していることを確認します。

ガードレール

• API の仕様を決して捏造しないでください。ドキュメントと SDK のソースに事実上の矛盾がある場合は、ソースに従ってスキルを記述し、その不一致を上流に報告する価値のある clerk-docs のバグの可能性として「未解決の質問」に記載してください。人によるレビューに回すのは、ソースが両方のパターンを支持していて、ドキュメントではどちらを推奨すべきか不明な、本当に規範的な曖昧さに限ります。
• スニペットは最小限（API の形式と制御フローを示すものとし、画面の装飾は含めない）にし、正規ドキュメント URL の引用を維持してください。
• スキルの実行ゲートの構造と文体を維持し、編集内容は既存のセクションに組み込んでください。
• レガシー API の禁止（ゲート：メソッドベースのフローを使用し、新しいコードでは prepareFirstFactor／setActive を使用しない）は、SDK 自体がレガシー API を再び正当化する場合にのみ緩和できます。そのような変更は、通常の編集ではなく重大な発見として扱ってください。
• インストール済みの node_modules のコピーを監査の根拠として使わないでください。そこに含まれるのは直近のインストールで取得されたものであり、監査対象のリリースとは限りません。
• コミットしないでください。明示的に依頼されない限り、ステージングとコミットはメンテナーに任せてください。

出力形式

# clerk-expo skill audit - <YYYY-MM-DD>

## Summary
<stamped vs current version, changelog entries reviewed, counts per bucket, largest drift>

## skills/clerk-expo/SKILL.md
### <section>
- [drift|gap|polish] <one-line description>
  - source: packages/expo/src/<...>:<line> (or docs/<...>.mdx:<line>)
  - target: skills/clerk-expo/SKILL.md:<line>
  - change: <diff or concise before/after>

## skills/clerk-expo/references/<file>.md
...

## skills/clerk-expo/evals/evals.json
...

## Open questions
...

メンテナーが各項目を個別に承認、却下、または適用できるよう、ひと目で確認しやすい形式にしてください。