rolecard-workshop-ops

Rolecard Workshop Ops

Shared communication

TW の平易な表現とガイダンスのルールを適用します。用語は初出時に説明し、ユーザーが選択した新人／入门／熟练／老手のレベルを維持し、どのレベルでも必要な変更やバグについて説明します。Soul モードと prose モードでも、この基本ルールは無効になりません。

Plugin runtime

この Skill がプラグイン、クラウドホスト、またはリモートマシンを通じて実行される場合は、開始時にプラグイン実行契約を読み、ホスト固有のコマンドを実行する前に、ホスト、ツール、永続化に関する確認事項を適用します。この Skill の対象範囲、認可、受け入れ基準を維持してください。

運用上の変更を書き込む前に、rolecard-workshop-ops ルートを指定して $consult-tavernweave-library を使用し、A0 とデプロイ／ワークショップのガイドを読み込みます。公開ガイダンスと、本番環境の接続先、認証情報、稼働状態、デプロイ認可は分けて扱ってください。

このスキルは、ワークショップのインフラと、ロールカードクライアント、公開カタログ、パッケージ Gateway、ID プロバイダー、レビューツール、ストレージ間の契約に使用します。障害がその境界を越えない限り、ローカルのロールカード UI 作業にはこのスキルを使用しないでください。

Operating Modes

モードを 1 つ選び、作業を始める前に明示します。

1. 読み取り専用の診断がデフォルトです。リポジトリの状態、設定名、ヘルスレスポンス、公開インデックス、ユーザーがすでに利用できるログ、契約テストを調べます。デプロイやリモート状態の変更は行いません。
2. 変更候補は、範囲を限定したパッチまたはデプロイ計画を準備する場合に使用します。対象となるファイル、サービス、動作の変更、検証方法、ロールバック手順を明示します。候補の提示は、デプロイの許可を意味しません。
3. 認可済みデプロイには、指定された環境へのデプロイまたは変更を行う明示的なユーザー依頼が必要です。実行直前に、解決済みの対象、現在のリリース、バックアップ／ロールバック手段、検証コマンドを再確認します。

依頼が「確認」「デバッグ」「監査」「引き継ぎ」「理由の調査」だけの場合は、読み取り専用の診断を続けます。

Resolve Parameters First

例からデプロイ先を推測してはいけません。以下の値を特定するか、ユーザーに確認し、チャットやログにシークレットを残さないでください。

パラメーター	意味
REPOSITORY_ROOT	カタログと Gateway を含むローカルリポジトリ
GATEWAY_ROOT	Gateway サービスのディレクトリ
STATIC_INDEX_URL	公開カタログ／インデックスの URL
GATEWAY_BASE_URL	Gateway の公開 HTTPS オリジン
HEALTH_PATH	読み取り専用のヘルスエンドポイントパス
SSH_TARGET	承認済みのリモートホスト別名、またはユーザーが指定したホスト
DEPLOY_COMMAND	リポジトリが管理するデプロイのエントリーポイント
VERIFY_COMMAND	リポジトリが管理するデプロイ前／デプロイ後の確認コマンド
SECRET_CONFIG	デプロイツールが使用するシークレットの保存元。モデルのコンテキストに読み込んではいけません

未解決のプレースホルダーが残っている場合、リモートコマンドを実行する前に拒否してください。シークレットの値、秘密鍵、OAuth クライアントシークレット、管理者トークン、セッション署名素材、未加工の ID プロバイダー識別子を出力してはいけません。

Architecture Boundary

• 静的ホストは、公開スキーマ、例、インデックス、互換性メタデータ、バージョン通知を公開します。
• Gateway は、パッケージの作成、詳細、更新、取り下げ、モデレーション状態、所有権、および認証済み API を管理します。
• オブジェクトストレージには、承認済みの公開パッケージと任意のメディアを保存します。認可データベースとして使用してはいけません。
• OAuth は、公開／更新／取り下げに必要な最小限の所有者 ID を確立します。プレイヤー追跡システムではありません。
• ロールカードクライアントは、公開データと認証済みの所有者向け API を利用しますが、サーバーの認証情報を含めてはいけません。
• インポートされたパッケージは、別途実行するプレビュー可能な適用トランザクションの前に、スキーマ、互換性、ポリシーの各チェックに合格する必要があります。

API またはクライアントのコンシューマーを変更する前に、architecture-and-contracts.mdを読んでください。

読み取り専用の診断手順

1. ファイルを変更せずに、現在のリポジトリとデプロイに関するドキュメントを確認します。
2. 既存の運用スクリプトとパッケージコマンドを探します。別のデプロイ経路を独自に作らないでください。
3. 公開ヘルスエンドポイント、静的インデックス、パッケージ一覧、パッケージ詳細のレスポンスを確認します。
4. Gateway の契約を、すべてのクライアント利用箇所および契約テストと照合します。
5. 値を読み取らずに、設定キー名と検証ロジックを確認します。
6. 認証情報、Cookie、認可ヘッダー、クエリ内のシークレット、個人データをマスキングしたうえで、対象を限定した失敗リクエストについて最近のログを確認します。
7. 失敗しているレイヤー、根拠、最小限の変更候補、検証方法、デプロイの承認が必要かどうかを報告します。

プロセスが正常であることを、OAuth、ストレージ、レビュー、パッケージ詳細、クライアント連携が機能している証拠として扱わないでください。

変更とデプロイの承認ゲート

承認済みの変更については、次の手順に従います。

1. 対象範囲を、1つの契約上または運用上の問題に限定します。
2. 現在のリリース識別子とロールバック方法を記録します。
3. リポジトリで管理されている静的チェック、契約テスト、ローカルのスモークテストを実行します。
4. 認証情報、デプロイ先情報、破壊的なコマンド、無関係な変更がないか、差分を確認します。
5. 解決された環境と明示的な承認を再確認します。
6. 既存のデプロイエントリーポイントを使用します。シークレットを手作業でコピーしたり、リモートファイルの変更方法を独自に考案したりしないでください。
7. ヘルス、公開インデックス、パッケージ詳細、認証状態、影響を受ける所有者／レビューのフローを検証します。
8. 必須のデプロイ後チェックに失敗した場合は、緊急パッチを重ねずに停止し、文書化されたロールバック手順を使用します。

承認、CORS、プライバシー、ロールバックのゲートについては、operations-and-security.md を参照してください。

契約ルール

• 公開一覧エンドポイントでは、承認済みで取り下げられていないパッケージのみを公開します。
• 詳細エンドポイントでは、検証とインストールに必要なパッケージペイロードを保持します。
• 作成、更新、取り下げでは、サーバー側で所有権を確認します。
• 更新とモデレーションの判断では、リビジョンまたは同等の楽観的同時実行制御を使用します。古い状態に基づく書き込みはフェイルクローズで失敗させます。
• クライアントが、権威あるモデレーション、所有権、リビジョン、監査の各フィールドを送信できないようにします。
• 認証ハンドオフ値は有効期間が短く、一度だけ使用でき、範囲を制限する必要があります。また、引き換え権限を持つ値を公開 URL で渡してはいけません。
• インストール、更新、アンインストールはトランザクションとして実行し、そのパッケージが所有するデータのみを変更します。
• API の形状変更は、Gateway、クライアント利用箇所、スキーマ／契約定義、スモークテストのすべてで整合するまで完了ではありません。

プライバシーの最低要件

所有権の確認に必要な最小限の識別情報のみを永続化します。たとえば、プロバイダーのスコープ内でキー付きハッシュ化した値と、ランダムな公開者識別子などです。個別かつ明示的な製品要件と法的根拠がない限り、メールアドレス、ニックネーム、アバター、プロバイダーの生 ID、IP プロファイル、行動プロファイルを永続化しないでください。

ログには、アクション、パッケージ識別子、仮名化された公開者識別子、結果、理由コード、時刻を記録します。アクセストークン、Cookie、認可ヘッダー、OAuth コード、生の識別情報、パッケージのシークレットは記録しないでください。

停止条件

次の場合は停止し、次の手順を正確に示してください。

• 必要な承認、アカウント確認、CAPTCHA、または外部の同意が不足している場合。
• 続行するために認証情報、秘密鍵、シークレットを公開する必要がある場合。
• 対象環境またはロールバック範囲を明確に特定できない場合。
• 検証済みの復旧手段がないまま、ユーザーパッケージ、ストレージ、監査履歴、本番データを削除する可能性がある操作の場合。
• CORS、OAuth、プロキシ、ストレージ、リリースポインターの変更によって、承認済みの範囲が気付かれないまま拡大する場合。

参考資料

• architecture-and-contracts.md：汎用サービスと API 契約。
• operations-and-security.md：読み取り専用チェック、承認ゲート、シークレット、CORS、デプロイ、ロールバック。
• provenance.md：公開派生物の境界。