portaly-sentry

Portaly Sentry — 決済連携のヘルスチェック

このスキルを使用して、Portaly Vibe の決済連携に対する包括的なセキュリティおよび信頼性のヘルスチェックを実行します。このスキルは、バイブコーディングツールを使用するエンジニア以外の方が、自信を持ってリリースできるように設計されています。出力は人にとってわかりやすく、実行に移しやすい内容にしてください。まず平易な言葉で概要を伝え、ユーザーが詳細を確認できるようにします。技術的な26行の表は、ユーザーから求められた場合にのみ提示してください。

このスキルは portaly-payment と併用します。正しい連携の基準となる正規の情報源と、同じ API コントラクトを使用します。

クイックスタート

ステップ 1 — 連携が存在することを確認する

• プロジェクトに Portaly Vibe の決済連携があることを確認します（portaly、callbackSecret、x-portaly-signature、またはチェックアウトセッションの作成コードを探してください）。
• 連携が見つからない場合は、その旨を伝えて続行します。決済固有のチェックは自動的にスキップされますが、一般的なチェック（DEP、ENV-002）は引き続き実行されます。

ステップ 2 — Sentry のチェック内容を平易な言葉で説明する

ほかのことを尋ねる前に、Sentry が実際に何をするのかをユーザーが理解できるよう、以下の導入文を表示してください。このステップは省略しないでください。初めて利用するユーザーには、「SIG」や「SUB」の意味がわかりません。

テンプレート：

Portaly Sentry checks your payment integration across 3 areas:
🏦 Is the payment flow itself done right?  signatures, callbacks, subscriptions
🔐 Are your merchant credentials safe?     env vars, credential management
🛡️ Is everything else hardened?            dependencies, web security, data handling
26 checks in total, graded by severity: CRITICAL / WARNING / INFO.

ステップ 3 — 対象プロジェクトとスキャン基準を尋ねる

デフォルトを選ばないでください。ユーザーに両方の質問をして、回答を待ちます。提案ではなく、確認事項として尋ねてください。

テンプレート：

Two things before I start:
① Which project should I scan? (e.g. ~/gratitude-app)
② Which standard do you want?
   🚀 Pre-launch    — pass all CRITICAL
   🔧 Routine check — pass all CRITICAL + WARNING
   🏆 Gold standard — pass all 26 (including INFO)
   📄 Report only   — scan and show the report, skip the fix workflow
   ⏰ Weekly auto   — schedule a recurring scan instead of scanning now

基準 → 対象範囲の対応（エージェント内部用。ユーザーにはこの表を表示しないでください）：

ユーザーの選択	レポートに含まれる内容	ブロックする重大度	修正ワークフロー
🚀 リリース前	全26項目のチェック	CRITICAL のみ	提案する
🔧 定期チェック	全26項目のチェック	CRITICAL + WARNING	提案する
🏆 ゴールドスタンダード	全26項目のチェック	すべての重大度	提案する
📄 レポートのみ	全26項目のチェック	該当なし	提案しない
⏰ 毎週自動	スキャンをスキップ → ステップ16へ進む	該当なし	該当なし

スケジュール実行以外の4つの基準では、いずれも全26項目をチェックします。最初の3つの違いは、レイヤー1の概要にある「Status」行で使用する合否のしきい値だけです（ステップ14を参照）。📄 レポートのみでは同じスキャンを実行しますが、レイヤー2（修正モードのプロンプト）はスキップし、レイヤー3の終了時点で完了します。監査、コードレビュ―への引き継ぎ、または今すぐ修正を約束せずに結果だけを確認したい場合に使用してください。

上級者向け。 ユーザーが1つのカテゴリだけをスキャンするよう明示的に求めた場合（例：「署名だけをスキャン」「SIGを再実行」）、SIG、SUB、CBK、ENV、SEC、WEB、DEP、DATAのいずれかを使う単一カテゴリモードとして受け付けてください。カテゴリコードは初めて利用するユーザーを混乱させるため、主な選択肢として提示しないでください。

前提条件

• 静的解析チェック（SIG、SUB、CBK、ENV、SEC、WEB、DATA）に認証情報は必要ありません。
• DEP チェックには、プロジェクトに package.json が必要です。
• 結果を Portaly に報告するには、ユーザーに PORTALY_API_KEY が必要です。

プロバイダー設定

報告エンドポイントのデフォルトは https://portaly.ai/api/creator-subscription/health-check-reports です。PORTALY_API_HOST を使用してホストを上書きできます（scripts/report.mjs ではすでに反映されます）。リポジトリのルートにある PROVIDER.md を参照してください。

ヘルスチェックのカテゴリ

SIG — 署名検証

コールバック署名の検証が Portaly の正規の実装と一致しているかをチェックします。

ID	チェック項目	重大度
SIG-001	安定した JSON のソート順に Object.entries().sort(([a],[b]) => a.localeCompare(b)) を使用している	CRITICAL
SIG-002	HMAC アルゴリズムが SHA-256 である	CRITICAL
SIG-003	5分より古いコールバックを拒否するタイムスタンプによるリプレイ防止がある	WARNING
SIG-004	署名の比較に crypto.timingSafeEqual を使用している	CRITICAL

SUB — サブスクリプションのライフサイクル

チェックアウトからキャンセルまでのフロー全体で、サブスクリプション ID が正しく保存され、使用されていることを確認します。

ID	チェック項目	重大度
SUB-001	チェックアウト完了後に subscriptionId（= sessionId）が保存されている	CRITICAL
SUB-002	冪等性キーを使用して重複するコールバックを処理している	WARNING
SUB-003	キャンセル／再開 API が保存済みの subscriptionId を使用している	CRITICAL

CBK — コールバックエンドポイント

コールバックエンドポイントの設定と動作を確認します。

ID	チェック項目	重大度
CBK-001	callbackUrl が HTTPS を使用している	CRITICAL
CBK-002	署名検証に失敗した場合、診断情報とともにログに記録される	WARNING
CBK-003	コールバックハンドラーが成功時に明示的に 200 を返す	INFO

ENV — 環境と認証情報

認証情報の管理と環境設定を確認します。

ID	チェック項目	重大度
ENV-001	PORTALY_API_KEY と PORTALY_CALLBACK_SECRET が .env ファイルまたはソースコード内で参照されている（.env、シークレットマネージャー、ランタイム環境変数など、何らかの仕組みを通じてキーが連携されていることを確認）	CRITICAL
ENV-002	機密情報を含む .env ファイルが Git の追跡対象外になっている（git check-ignore で確認。.env.example はコミットするテンプレートのため対象外）	CRITICAL
ENV-003	ソースファイルに API キーまたはコールバックシークレットがハードコードされていない	CRITICAL

SEC — セキュリティのベストプラクティス

連携におけるセキュリティ対策を確認します。

ID	チェック項目	重大度
SEC-001	クライアント側／ブラウザーからアクセス可能なコードにコールバックシークレットや API キーが含まれていない	CRITICAL
SEC-002	監査証跡としてコールバックの生の本文が保存されている	INFO
SEC-003	シークレットが環境変数から読み込まれている（ローテーションに対応可能）	INFO
SEC-004	コールバックエンドポイントで過度に許容的な CORS（Access-Control-Allow-Origin: *）が設定されていない	WARNING
SEC-005	決済関連ページで Content-Security-Policy ヘッダーが設定されている	INFO

WEB — Web セキュリティの基本

決済フローでよくある Web セキュリティ上の問題がないか確認します。

ID	チェック項目	重大度
WEB-001	successRedirectUrl／cancelRedirectUrl がドメインの許可リストに照らして検証されている	CRITICAL
WEB-002	エラーレスポンスでスタックトレース、内部パス、DB スキーマが公開されない	WARNING
WEB-003	コールバックエンドポイントで Content-Type: application/json が検証されている	WARNING
WEB-004	コールバックエンドポイントでリクエスト本文のサイズ制限が適用されている	WARNING

DEP — 依存関係のセキュリティ

プロジェクトの依存関係に既知の脆弱性がないか確認します。

ID	チェック項目	重大度
DEP-001	npm audit／pnpm audit で重大または高深刻度の CVE が報告されない	CRITICAL
DEP-002	ロックファイル（package-lock.json／pnpm-lock.yaml）が存在し、コミットされている	WARNING

DATA — データ取り扱いのセキュリティ

安全なデータ取り扱いが実践されているか確認します。

ID	チェック項目	重大度
DATA-001	データベースに書き込む前に、コールバックペイロードのフィールドが検証されている（型／長さ）	WARNING
DATA-002	ログに完全な API キー、コールバックシークレット、生の顧客個人情報が含まれていない	WARNING

ワークフロー

ステップ 4 — 連携ファイルを特定する

プロジェクト内で、Portaly の決済連携に関連するファイルを検索します。

• crypto をインポートしているファイル、または HMAC 操作を含むファイル
• portaly、x-portaly-signature、x-portaly-timestamp、callbackSecret、PORTALY_CALLBACK_SECRET を含むファイル
• コールバックのルートハンドラー（Express のルート、Next.js の API ルート、Cloud Functions の HTTP トリガー）
• チェックアウト完了に関連するコンテキストで subscriptionId、sessionId を含むファイル
• successRedirectUrl、cancelRedirectUrl を含むファイル

ファイル一覧を作成し、各ファイルを関連するチェックカテゴリに対応付けます。

ステップ 5 — SIG チェックを実行する

署名関連の各ファイルについて、次を確認します。

1. ソート順のパターンを確認します。../portaly-payment/scripts/sign_callback.mjs にある標準実装と比較します。
2. HMAC アルゴリズムを確認します。createHmac('sha256', ...) が使われていることを検証します。
3. タイムスタンプ検証を確認します。x-portaly-timestamp が現在時刻と照合され、5 分間の許容範囲が設けられていることを確認します。
4. 比較方法を確認します。=== や == ではなく、crypto.timingSafeEqual が使われていることを検証します。

参照：scripts/check_signature_sort.mjs で、このステップを自動化できます。

ステップ 6 — SUB チェックを実行する

サブスクリプション ID のライフサイクルを追跡します。

1. コールバックハンドラーで、status === 'completed' の後に何が永続化されるかを確認します。保存される値は sessionId にしてください（Portaly の現在の仕様では sessionId は subscriptionId と同じです）。
2. 冪等性を確認します。処理を実行する前に、この sessionId がすでに処理済みかどうかをハンドラーが確認しているでしょうか。
3. キャンセル／再開のコードパスを追跡します。コールバックで書き込まれたものと同じ subscriptionId フィールドを読み取り、/subscriptions/{subscriptionId}/cancel または /resume に渡していることを検証します。

参照：scripts/check_subscription_lifecycle.mjs で、このステップを自動化できます。

ステップ 7 — CBK チェックを実行する

1. callbackUrl が https:// を使って構築されているか確認します。
2. 署名検証の失敗時の分岐を確認します。診断情報（タイムスタンプ、ペイロードのハッシュ、期待値と実際の値）がログに記録されているでしょうか。
3. 成功時の分岐が明示的に 200 ステータスを返すことを確認します。

ステップ 8 — ENV チェックを実行する

1. ツリー内のあらゆる場所（ルート、functions/、apps/*、packages/* など）で .env* ファイルを探します。
2. ENV-001 は、PORTALY_API_KEY と PORTALY_CALLBACK_SECRET の両方が参照されていれば合格です。参照箇所は .env ファイル内でも、ソースコード内での名前の使用でもかまいません。コード内で名前が使われていれば（例：process.env.PORTALY_API_KEY、defineSecret('PORTALY_API_KEY')、その他の使用方法）、プロジェクトが何らかの仕組み（.env、シークレットマネージャー、ランタイム環境変数、シェルのエクスポートなど）を通じてキーを設定していることを意味します。スクリプトは、どのプラットフォームが使われているかを把握する必要はありません。両方のキーが常に必要です。外部への呼び出しには PORTALY_API_KEY、支払い結果の検証には PORTALY_CALLBACK_SECRET を使います。
3. ENV-002：各機密情報を含む .env ファイルが gitignore の対象になっていることを検証します。階層的なパターン（例：ルートの .gitignore にある **/.env が functions/.env にも適用される場合）を考慮するため、git check-ignore を使います。.env.example はコミットすることを想定したプレースホルダーテンプレートなので、対象外とします。機密情報を含む .env ファイルがない場合、またはプロジェクトが Git リポジトリではない場合、このチェックは合格です（漏えいする可能性のあるものはありません）。
4. ENV-003：node_modules と .env を除くソースファイルを grep し、リテラルの pcs_live_、pcs_test_、またはコールバックシークレットと思われる文字列がないか確認します。

ステップ 9 — SEC チェックを実行する

1. 通常ブラウザーに配信されるディレクトリ（クライアントコンポーネント用の src/、public/、app/、pages/）にあるファイルに、API キーまたはコールバックシークレットが含まれていないか確認します。シークレットを含む NEXT_PUBLIC_ 接頭辞付き環境変数にも注意します。
2. 監査用に、コールバックの生の本文がデータベースに保存されているか確認します。
3. シークレットがハードコードされず、process.env または同等の方法から読み込まれていることを検証します。
4. コールバックエンドポイントに CORS ミドルウェアがあるか確認し、Access-Control-Allow-Origin: * を検出した場合は問題として報告します。
5. 成功／キャンセル時のリダイレクトページに CSP ヘッダーがあるか確認します。

ステップ 10 — WEB チェックを実行する

1. successRedirectUrl と cancelRedirectUrl がリダイレクトに使われる前に、信頼できるドメインの許可リストと照合して検証されているか確認します。
2. コールバックルートのエラー処理を確認します。catch ブロックが、完全なエラースタックをレスポンス本文に含めて送信しないことを確認します。
3. コールバックエンドポイントが Content-Type ヘッダーを検証していることを確認します。
4. リクエスト本文パーサーのサイズ制限（例：express.json({ limit: '1mb' }) または同等の設定）があるか確認します。

ステップ 11 — DEP チェックを実行する

1. package.json がある場合は、npm audit --json または pnpm audit --json を実行し、出力を解析して重大度が critical または high の脆弱性がないか確認します。
2. package-lock.json または pnpm-lock.yaml が存在し、.gitignore の対象になっていないことを確認します。

ステップ 12 — DATA のチェックを実行する

1. データベースへの書き込み前に、コールバックペイロードのフィールドが検証されているか確認します（型チェック、長さ制限、サニタイズ）。
2. ログ出力（console.log、console.error、logger.）を検索し、秘密情報や PII が漏えいする可能性がないか確認します。コールバックペイロード全体、API キー、またはコールバックシークレットを記録しているものがあれば、フラグを立てます。

ステップ 13 — 結果を Portaly に同期する（任意）

すべてのチェックを実行した後、概要を提示する前に、スキャン結果をユーザーの Portaly ダッシュボードに同期するかどうかを確認します。今同期しておけば、ステップ 14 のレイヤー 1 の概要に共有可能なレポートリンクを含められます。

通信方式は 2 つあります。利用可能な場合は MCP を優先してください。

パス A — MCP（優先、追加設定不要）。 エージェントが Vibe MCP に接続されている場合、vibe_report_health_check ツールを利用できます。このツールはエージェントの既存の MCP 接続を使用するため、PORTALY_API_KEY は不要です。簡潔に同意を求めてから、スキャンペイロードを指定してツールを呼び出します。レスポンスの dashboardUrl をレイヤー 1 のダッシュボードリンクとして使用します。入力スキーマについては、references/health-check-contract.md の「MCP reporting」を参照してください。

パス B — REST API（フォールバック）。 MCP に接続されておらず、ユーザーの環境に PORTALY_API_KEY が設定されている場合は、scripts/report.mjs の実行に切り替えます。このスクリプトは process.env.PORTALY_API_KEY からキーを読み取り、https://portaly.ai/api/creator-subscription/health-check-reports に POST します。キーをインラインで指定した curl または fetch を独自に作成するよりも、この方法を優先してください。スクリプトの標準出力（Dashboard: <url> の行）にある dashboardUrl を、レイヤー 1 のダッシュボードリンクとして使用します。リクエスト／レスポンススキーマの詳細については、references/health-check-contract.md の「Report API Contract」を参照してください。

ルール：

• 明示的なユーザーの同意なしに、どちらのパスも呼び出さないでください。
• どちらのパスも利用できない（MCP なし、キーなし）場合、または呼び出しに失敗した（例：REST で 404）場合は、同期を行わず、そのことを伝えずにダッシュボードリンクなしでステップ 14 に進んでください。概要の提示を妨げないでください。
• 同じスキャンに対して両方のパスを呼び出さないでください。どちらか一方を選んでください。

ステップ 14 — 概要を提示する（表全体は表示しない）

ユーザーに最初に表示するのは、平易な言葉で書かれた概要でなければなりません。26 行の表ではありません。 技術レポート全体はダッシュボードに表示します。ローカルで表示するのは、ユーザーが [C] を選んだ場合、ユーザーが 📄 レポートのみモードの場合、またはダッシュボードへのレポート出力が利用できない場合に限ります。

以下のレイヤーを、最大 3 つまで、この順番で出力します（📄 レポートのみモードではレイヤー 1 とレイヤー 3 のみを出力します。詳細は以下を参照してください）。

レイヤー 1 — 平易な言葉での概要（常に表示）

references/fix-explanations.md からタイトルを読み込み、新たな表現を独自に作成しないでください。references/health-check-contract.md の「Health Score Formula」にある計算式を使って、チェックごとの結果からヘルススコアを算出します。ダッシュボードに表示されるものと同じスコアです。

テンプレート：

📊 Payment integration health check — {projectName}
   Health score: {score}/100  ({band: Healthy | Needs attention | At risk})

🟢 Passing   {passedCount} checks    looking good
🟡 Review    {warnedCount} warnings  take a look this week
🔴 Critical  {failedCount} blockers  must fix before launch

Status: {status_line}

Top {min(3, failures)} things to fix:
1. {plain title from fix-explanations.md} ({ID})
2. ...
3. ...

🔗 Full report (all 26 checks, fix guidance, history)
{dashboard_url}

スコアの区分（ダッシュボードと一致させてください）：

スコア	区分
90–100	健全
70–89	要注意
0–69	リスクあり

{status_line} は、ステップ 3 で選択したスキャン標準に基づいて決定します（スコアとは無関係です。スコアは参考情報であり、起動可否は標準によって判定します）。

標準	「安全に起動可能」とする条件
🚀 起動前	CRITICAL の失敗が 0 件
🔧 定期チェック	CRITICAL および WARNING の失敗が 0 件
🏆 ゴールド標準	26 件すべてのチェックで失敗が 0 件

✅ Safe to launch または ❌ Not safe to launch yet のどちらかを使用してください。その中間の表現は使用しないでください。{dashboard_url} はステップ 13 から返された dashboardUrl です。ステップ 13 をスキップした場合、または値が返されなかった場合は、🔗 Full report ブロック全体（ラベル行と URL 行の両方）を削除してください。

📄 レポートのみの場合は、Status: 行を完全に省略し（このモードには起動可否の判定がありません）、代わりに Mode: 📄 Report only — fix workflow disabled を使用してください。レイヤー 1 のそれ以外の部分は変更しないでください。

レイヤー 2 — 修正モードの選択（概要の直後に表示。ただし、📄 レポートのみの場合を除く）

📄 レポートのみモードでは、レイヤー 2 を完全にスキップして、レイヤー 3 に進んでください。[A]／[B]／[C] のプロンプトは表示しないでください。ユーザーはすでに修正を行わないことを選択しています。

テンプレート：

─────────────────────────────────────
Want to start fixing now?
[A] Yes, walk me through all of them in order (recommended)
[B] Just the 🔴 critical ones (fastest path to launch)
[C] Show me the full report first

ユーザーの回答に応じて、次のように進みます。

• [A] → すべての失敗を対象に、重大度の高い順（CRITICAL → WARNING → INFO）で表示する対話型修正ワークフロー
• [B] → CRITICAL の失敗のみを対象とする対話型修正ワークフロー
• [C] → レイヤー 3

レイヤー 3 — 技術レポート全体（[C] の場合、📄 レポートのみモードの場合、またはダッシュボードでのレポートが利用できない場合）

カテゴリ別にまとめた 26 行の表全体を表示します。形式：

## Portaly Sentry — Health Check Report
Project: {project_name} | Scan: {ISO timestamp} | Mode: {manual|scheduled}

### SIG — Signature Verification
| # | Check | Severity | Status |
|---|-------|----------|--------|
| SIG-001 | Stable JSON sort order | CRITICAL | [PASS] |
| ... | ... | ... | ... |

### SUB — Subscription Lifecycle
| # | Check | Severity | Status |
|---|-------|----------|--------|
| ... | ... | ... | ... |

(repeat for CBK / ENV / SEC / WEB / DEP / DATA)

---

Summary: X/26 passed | Y CRITICAL failures | Z warnings | W skipped

### Fix: {ID} — {Check Name}
File: {file_path}:{line}
{description of the issue}
{code diff showing the fix}

ステップ 15 — 対話型修正ワークフロー（項目ごとに確認）

レイヤー 2 でユーザーが [A]（すべて修正）または [B]（CRITICAL のみ修正）を明示的に選択した場合に限り、このワークフローに進みます。失敗項目を重大度の高い順（CRITICAL → WARNING → INFO）に、必ず一度に 1 項目ずつ提示し、ファイルに変更を加える前に確認を待ってください。

📄 レポートのみモードでは、このステップには仕様上進めません。レイヤー 2 は表示されないため、[A]／[B] が選択されることもありません。ユーザーが後から修正の開始を希望した場合は、新しいリクエストとして扱い、このワークフローに進む前にレイヤー 2 の選択肢を再度提示してください。

項目ごとのテンプレート

失敗項目ごとに、以下のブロックを表示します。平易な説明文はすべて references/fix-explanations.md から取得し、その場で言い換えないでください。ID、ファイルパス、差分内のコード、[Y]/[N]/[?]/[STOP] キーはそのまま使用してください。

テンプレート：

🔴 Item {n} of {m}        | Progress {progress_bar} {percent}%
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Fix: {plain title} ({ID})

📍 Which file?
{file_path} ({change summary, e.g. "add 1 import, change 3 lines"})

❓ Why does this matter?
{why it matters, from fix-explanations.md}

🔧 Preview:
{unified diff, - old / + new}

✅ Affects:       {affects, from fix-explanations.md}
✅ Doesn't affect: {doesn't affect, from fix-explanations.md}
─────────────────────────────────────
Apply this fix?
[Y] Go ahead, apply it
[N] Skip this one
[?] I'd like to understand more first
[STOP] Pause here, I'll come back later

ルール

• 一度に 1 項目ずつ。 複数の修正をまとめて確認しないでください。[B] に CRITICAL の項目が 3 つある場合も、それぞれについて Y/N を確認します。
• 重大度アイコンを見出しに合わせます。 CRITICAL には 🔴、WARNING には 🟡、INFO には ⚪ を使用してください。
• 進捗バー： 塗りつぶしに ▓、空きに ░ を使用し、合計 7 ブロックにします。3/7 の例：▓▓▓░░░░。
• 差分にはユーザー自身のコードスタイルを使用します。 モジュールシステム（ESM と CommonJS）、変数名、フレームワークの慣例を合わせてください。典型的な修正パターンは references/common-pitfalls.md と ../portaly-payment/scripts/sign_callback.mjs から取得し、ユーザーのスタイルに合わせてください。
• ユーザー向けのテキストでは、CRITICAL／WARNING／INFO のラベルをそのまま表示しないでください。 「重大／修正推奨／できれば対応」のような自然な表現を使い、🔴／🟡／⚪ のアイコンで視覚的に重大度を示してください。

各回答への対応

完全一致の文字列ではなく、意図に基づいてユーザーの返答を判断してください。キーとなる文字は標準的なトリガーですが、英語またはユーザーの言語での同等の表現も同じ意図として扱います。

意図	標準トリガー	アクション
適用	[Y]（または「はい」／「適用」／「OK」／同等の表現）	編集を適用し、1 行で成功を伝え（例：✅ Applied {ID}）、次の項目に進みます。
スキップ	[N]（または「スキップ」／「いいえ」／同等の表現）	ファイルを変更しません。⏭️ Skipped {ID} と記録し、次の項目に進みます。
説明	[?]（または「なぜ」／「詳しく教えて」／同等の表現）	references/common-pitfalls.md から該当する落とし穴の項目を読み込みます（誤った実装と正しい実装、および説明）。説明後、同じ Y/N/?/STOP の選択肢で再度確認します。テンプレート全体は再表示しません。
停止	[STOP]（または「一時停止」／「後で」／同等の表現）	直ちに停止します。再開用の概要を表示します：Applied X / Skipped Y / Remaining Z. Say "resume fixing" any time and I'll pick up at item {n}. 先に進まないでください。

最後の項目の後

テンプレート：

🎉 Fix session complete
✅ Applied: {X}
⏭️ Skipped: {Y}
─────────────────────────────────────
Suggested next steps:
1. Run your usual tests or try a checkout end-to-end
2. Re-run Sentry to confirm everything passes now
3. If you have a Portaly API key, sync the results to your dashboard

ステップ 16 — 自動スキャンを設定する（任意）

簡単なものから最も厳格なものまで、3 つの方法があります。すべて提示し、ユーザーに選んでもらいます。

オプション A — GitHub Actions（GitHub リポジトリがあるすべてのプロジェクトに推奨）

references/ci-setup-guide.md のテンプレートを使って、.github/workflows/portaly-sentry.yml を作成するようユーザーに伝えます。次に、PORTALY_API_KEY を GitHub リポジトリのシークレットとして追加します。 これは main へのプッシュごと、および毎週月曜日に実行され、CRITICAL の問題が見つかった場合はマージをブロックします。

オプション B — pre-push git フック（ローカルマシンでの適用）

インストールするには、次のコマンドを一度実行します。

cat > .git/hooks/pre-push << 'EOF'
#!/bin/sh
set -e
node "$(git rev-parse --show-toplevel)/.claude/skills/portaly-sentry/scripts/report.mjs" \
  --dir "$(git rev-parse --show-toplevel)" --fail-on critical
EOF
chmod +x .git/hooks/pre-push

オプション C — scripts/report.mjs を使った自動スクリプトランナー

任意の CI システムまたはスケジュールタスクから、自動化スクリプトを直接指定します。スクリプトは環境変数から PORTALY_API_KEY を読み取ります。値を直接埋め込まず、CI のシークレットストア、シェルプロファイル、または .env ローダーで設定してください。

# PORTALY_API_KEY exported via CI secret / shell / .env
node .claude/skills/portaly-sentry/scripts/report.mjs \
  --dir . --scan-type scheduled --fail-on critical

--fail-on critical を指定すると、CRITICAL の問題が見つかった場合にコマンドが 1 で終了します。すべての CI システムでビルド失敗として扱われます。

CLI の全リファレンスと設定手順については、references/ci-setup-guide.md を参照してください。

出力スタイル

• 表ではなく、平易な言葉による概要（レイヤー 1）から始めます。 26 行の表はレイヤー 3 であり、リクエストされた場合にのみ表示します。
• 失敗したチェックの名称には、references/fix-explanations.md の簡潔なタイトルを使います。見出しに「SIG-004」のような ID をそのまま表示してはいけません。タイトルの後ろに ID を括弧付きで記載します。
• [PASS]、[FAIL]、[WARN]、[SKIP] のステータス表示は、レイヤー 3 の表の中でのみ使用します。
• レイヤー 3 のチェックは、カテゴリ（SIG、SUB、CBK、ENV、SEC、WEB、DEP、DATA）ごとにまとめます。
• 失敗ごとの修正手順は、表の後にまとめて表示するのではなく、インタラクティブな修正ワークフローで一度に 1 件ずつ、明示的な確認を得て提示します。
• 静的解析は読み取り専用です。ユーザーが [A] または [B] を選んだ後にのみ、修正モードに入ります。

推奨する応答形式

標準モード（🚀 リリース前 / 🔧 定期チェック / 🏆 ゴールドスタンダード）：

1. 🔴/🟡/⚪ の件数、ステータス行、失敗 TOP 3、ダッシュボードリンクを含む平易な言葉による概要（レイヤー 1）
2. 修正モードの選択肢を提示：[A] / [B] / [C]（レイヤー 2）
3. 次に、以下のいずれかを実行します。
   • [A] または [B] → インタラクティブな修正ワークフローに入る（一度に 1 件ずつ）
   • [C] → カテゴリごとにまとめたレイヤー 3 の全レポートを表示する
4. 任意：Portaly へのレポート送信確認

📄 レポートのみモード：

1. 平易な言葉による概要（レイヤー 1。「Status:」の代わりに「Mode:」の行を使用）
2. カテゴリごとにまとめたレイヤー 3 の全レポート
3. ここで終了します。レイヤー 2 を表示せず、インタラクティブな修正ワークフローにも入りません。
4. 任意：Portaly へのレポート送信確認

ガードレール

• ユーザーが修正モードに入るまでは読み取り専用です。 検出、スキャン、Layer 1/3 のレポートでは、ユーザーのコードに触れてはいけません。Layer 2 でユーザーが [A] または [B] を選択した後に限り、インタラクティブ修正ワークフローに進めます。また、その中でも個別の項目について [Y] の確認を得た後に限り、編集を適用してください。1 回の確認で複数の修正を一括適用してはいけません。
• 📄 レポートのみの場合は、どのような場合も読み取り専用です。 ユーザーがステップ 3 で「レポートのみ」を選択した場合、レポートで CRITICAL な問題が見つかったとしても、Layer 2 を表示せず、インタラクティブ修正ワークフローにも進まないでください。ユーザーが後から修正を依頼した場合は、新たなリクエストとして扱い、何かを適用する前に [A]/[B]/[C] を再度提示してください。
• 秘密情報の値を自分の出力に含めないでください。 サンプルコマンド、ヘッダー、スニペット、ログ、PR/コミットの内容など、作成するものでは、認証情報を変数名（$PORTALY_API_KEY）だけで参照してください。pcs_live_... のような実際の値は決して含めないでください。キーをヘッダーに含めた curl/fetch を自分で組み立てるより、scripts/report.mjs または MCP の vibe_report_health_check ツールを優先してください。チェックでユーザーのソース内に秘密情報が見つかった場合は、表示する前に *** でマスクしてください。ユーザーが明示的にキーを提示した場合（例：「これを .env に保存して」「このキーをテストして」）の支援は問題ありません。このルールは、自発的に作成する内容に適用されます。
• portaly-payment を相互参照してください。 正式なコールバック検証仕様とサブスクリプションのライフサイクル契約については、../portaly-payment/references/api-contract.md を読み込んでください。
• ユーザーのスタックを決めつけないでください。 修正を推奨する前に、Express、Next.js（App Router / Pages Router）、Cloud Functions、Fastify、またはバニラ Node.js のどれが使われているか確認してください。
• ユーザーのコードスタイルに合わせてください。 修正を推奨する際は、ユーザーが既に使っているパターン、変数名、モジュール方式（ESM と CommonJS）に合わせたコードを作成してください。
• インテグレーションが見つからなくても、スキャンを続けてください。 決済固有のチェックには [SKIP] を付けます。DEP と ENV-002 は引き続き実行してください。
• レポート API の利用は任意です。 ユーザーの同意なしにヘルスチェックのレポート API を呼び出さないでください。API が 404 を返した場合は、何も伝えずにスキップし、結果をローカルで表示してください。
• DEP チェックには package.json が必要です。 package.json がない場合は、DEP チェックをスキップし、[SKIP] と記載してください。
• Windows のエンコーディング。 Windows では、非 ASCII 文字を含む API 呼び出しの前に chcp 65001 を実行してください。

リソース

• references/health-check-contract.md チェック項目の完全な定義、重大度、合格／不合格の基準、レポート API の契約を確認する際に使用します。
• references/common-pitfalls.md 実際の統合で見つかった既知のバグについて、誤った実装と正しい実装、検出方法を詳しく確認する際に使用します。Interactive Fix Workflow でユーザーが [?]（詳細を説明）を選択したときに読み込みます。
• references/fix-explanations.md 26 個すべてのチェックについて、ユーザー向けの平易な説明文を確認する際に使用します。平易なタイトル、重要な理由、影響するもの、影響しないものを記載しています。Layer 1 の概要表示時と、Interactive Fix Workflow の各項目の表示時に読み込みます。その場で言い換えず、概要と項目ごとの表示で正規の表現を一貫して使用してください。
• scripts/report.mjs 完全自動の CI/CD スキャンに使用します。26 個すべてのチェックを実行して書式付きレポートを出力し、結果を portaly.ai に POST します。CI の終了コードを制御する --fail-on critical を受け付けます。
• scripts/computeHealthScore.mjs 0～100 のヘルススコア計算式の正規の実装です。report.mjs からインポートされ、Vibe ダッシュボードにも反映されるため、スキルのターミナルとダッシュボードに常に同じ数値が表示されます。
• scripts/check_signature_sort.mjs プロジェクトファイル全体で署名ソートのパターンを自動検証する際に使用します。report.mjs から内部的に呼び出されます。
• scripts/check_subscription_lifecycle.mjs サブスクリプション ID のライフサイクルを自動追跡する際に使用します。report.mjs から内部的に呼び出されます。
• references/ci-setup-guide.md 自動スキャン用に GitHub Actions、プッシュ前フック、または npm スクリプトを設定する場合に使用します。
• 相互参照：../portaly-payment/scripts/sign_callback.mjs Portaly コールバック署名の正規の実装です。正しい実装の参考として使用します。
• 相互参照：../portaly-payment/references/api-contract.md 信頼できる API 契約です。コールバックのペイロードフィールド、サブスクリプションのライフサイクルエンドポイント、subscriptionId === sessionId の契約を確認する際に使用します。