ae-project-semantic

ae-project-semantic

プロジェクトセマンティクスとは、プロジェクト全体で統制される L2 のビジネス概念、ルール、計算規約、およびデフォルトのアセット選択方法です。ダッシュボードやレポートより上位に位置します。ダッシュボード、レポート、イベント、プロパティ、メトリクスは L1 の証拠および実行アセットであり、それ自体がプロジェクトセマンティクスになることはありません。

ae-cli のみを使用してください。推奨、承認、リリースのためにデータベースへ直接書き込まないでください。

境界

• このスキルは、プロジェクトセマンティクスの推奨を生成または評価する場合に使用します。
• 分析タスクで公開済みのプロジェクトセマンティクスを利用する場合は、ae-analysis を使用します。
• フロントエンドでは候補の確認、編集、承認、却下、公開ができますが、推奨を生成してはいけません。
• 統制された認証済みのダッシュボード／レポートから開始してください。より広範なプロジェクトアセットを調査できるのは、ユーザーの明示的な同意を得た後に限ります。その場合も、証拠と信頼度における権威レベルの低さを維持してください。イベント、プロパティ、メトリクス、背景資料、メモは補足的な証拠としてのみ使用でき、L2 候補の主題にはできません。

必須ワークフロー

1. プロジェクトとホストを特定します。
2. 候補を調査する前に、推奨に関する以下の両方のリファレンスを読みます。
   • references/recommendation-quality.md：統制された L2 品質基準。
   • references/query-routing-v5.md：現在のクエリルーティング、想起のショートカット、分析プレイブックの検出プロトコル。
3. 既存の公開済みプロジェクトセマンティクスを確認します。

ae-cli project-semantic list --project-id <project_id>

4. デフォルトでは、統制された認証済みプロジェクトアセットとセマンティックスナップショットのコンテキストをエクスポートします。

ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope governed --output <tmp>/project-semantic-assets --force

--host がデプロイ済み分析ゲートウェイではなく、ローカルで起動した Common サービスを直接指している場合は、そのコマンドに限って空のゲートウェイドメインを設定し、リクエストが Common のネイティブな /api/cli/v1 ルートを使用するようにしてください。このオーバーライドをグローバルにエクスポートしないでください。

AE_CLI_CAPABILITY_GATEWAY_DOMAIN= ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope governed --output <tmp>/project-semantic-assets --force --host http://127.0.0.1:8992

5. スキャン前に、asset_scope、exported_asset_count、authenticated_asset_count、unauthenticated_asset_count、truncated、ワークユニット数、定義ファミリー数を確認します。truncated=true の場合、パッケージが互換性上の制限に達したことを警告してください。統制パッケージの情報が少なすぎて有用な問題フレームを作成できない場合は、実際の件数を報告し、アクティブなコラボレーション用アセットを再エクスポートするか尋ねてください。自動的に範囲を広げないでください。

ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope collaborative --output <tmp>/project-semantic-assets --force

それでもパッケージの情報が少なすぎる場合は、件数を報告したうえで、有効なプロジェクトのすべてのダッシュボード／レポートと、それらが参照するメタデータをエクスポートするか、別途尋ねてください。

ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope all_visible --output <tmp>/project-semantic-assets --force

governed は、直近 90 日間における認証済み、コラボレーション対象、かつアクティブなアセットです。collaborative では認証要件のみが除外されます。all_visible では認証、コラボレーション、最終利用日のフィルターが除外されますが、削除済み、凍結済み、非表示、オフライン、その他無効なアセットは引き続き除外されます。エクスポートはプロジェクト管理者のみが実行できます。all_visible 内ではユーザーごとの可視性フィルターは必要ありません。アセットの認証状態は独立したガバナンス書き込み操作であり、スキャンによって暗黙的に変更してはいけません。

6. パッケージを以下の順序で読みます。

   • 除外とリビジョンのコンテキストを構築するため、存在する場合は manifest.json、.asset-package.json、catalog/published.jsonl、catalog/disabled.jsonl、catalog/active-candidates.jsonl、catalog/rejected-candidates.jsonl。
   • ダッシュボードを優先した調査キューとして indexes/work-units.jsonl を使用します。利用優先度順を維持しながら、異なるビジネステーマを順に調査します。
   • 再利用可能な定義のバリエーションを比較するため、indexes/definition-families.jsonl とコンパクトなダッシュボード／レポートレコード。
   • 補足的な証拠として indexes/asset-directory.jsonl と indexes/governance-coverage.jsonl。
   • 候補が含まれるファミリー、または競合するファミリーに限り details/normalized/** を使用し、正規化された定義では不十分な場合に限り details/raw/** を使用します。 このサービスは、決定論的な解析、キー項目の正規化、定義の署名、使用順序、カタログの組み立てを担います。エージェントは、ビジネストピックの発見、根拠の解釈、反例の確認、候補の文言作成を担います。表示名、説明、注記は解釈の根拠として扱いますが、それだけで、ほかの点では同一の定義を別物と見なすことはありません。すべての詳細ファイルを最初からコンテキストに読み込んだり、ビジネス上の判断をプロジェクト固有のキーワードテーブルや決定論的なテンプレート生成ツールに委ねたりしないでください。

7. 提案する動作を、公開済み、無効、有効な候補、却下済みの各カタログと比較します。無効な意味は抑制コンテキストとして扱います。推奨生成を通じて、それらを消費、再作成、更新しないでください。プロジェクト管理者は、後から明示的に有効化できます。真に新しい意味に対してのみ CREATE を生成し、有効な意味に実質的な改訂が必要な場合は UPDATE を生成します。パッケージですでにカバーされている場合は、候補を生成しません。新規候補がゼロでも、推奨結果として正常です。

8. エージェントが作成したファイルを、エクスポートされた正確なパッケージに対して検証します。このコマンドは、必須フィールド、サポート対象の列挙値、カタログの競合、重複するフィンガープリント、解決可能な根拠参照など、決定論的な契約ルールのみを確認します。passed=true は、意味品質の承認を示すものではありません。

ae-cli project-semantic candidate validate --asset-package <tmp>/project-semantic-assets --submit-file <tmp>/project-semantic-candidates.json

9. 変更されていない候補ファイルと、引用されている根拠について、エージェントによる品質レビューを別途実施します。「高品質の基準」と references/recommendation-quality.md を適用します。生成パス自身による文言の承認に頼らないでください。各候補について、具体的な所見と根拠参照を添えて、PASS、REVISE、INSUFFICIENT_EVIDENCE のいずれかを記録します。提出するすべての候補が PASS になるまで、修正と、決定論的な検証およびエージェントレビューの両方を繰り返します。内容の薄い埋め草を含むより、候補がない推奨を正常に返す方が望ましいです。

10. 検証とエージェントレビューが完了したファイルを、変更せずに提出します。.asset-package.json.snapshot_hash または candidate validate が返す snapshot_hash を使用します。

ae-cli project-semantic candidate submit --project-id <project_id> --submit-file <tmp>/project-semantic-candidates.json --snapshot-hash <snapshot_hash>

11. 完全なクローズドループを検証する際は、CLI を通じてレビューし、有効化します。

ae-cli project-semantic candidate list --project-id <project_id>
ae-cli project-semantic candidate get --project-id <project_id> --candidate-id <candidate_id>
ae-cli project-semantic candidate enable --project-id <project_id> --candidate-ids '["candidate_1"]'
ae-cli project-semantic get --project-id <project_id> --id <semantic_id> --mark-used

ライフサイクル管理は、意図的に推奨レビューとは分離されています。

ae-cli project-semantic disable --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>
ae-cli project-semantic list --project-id <project_id> --status disabled
ae-cli project-semantic delete-impact --project-id <project_id> --semantic-id <semantic_id>
ae-cli project-semantic delete --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>
ae-cli project-semantic enable --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>

無効化とは、「消費せず、再度推奨しない」という意味です。無効状態からは、同じ意味を有効にするか、影響を確認して物理的に削除できます。物理的に削除すると、その意味は存在しなくなり、今後のスキャンで再発見される可能性があります。推奨を再生成する目的だけで削除しないでください。

厳格な品質基準

次のすべてを満たさない候補ファイルは受け入れられません。

• 管理対象の根拠から開始するか、明示的に承認されたより広いスコープを記録し、認証されていないアセットに依存する主張の確信度を下げていること。
• 候補を生成する前に、L2 の業務トピックドメインごとにグループ化していること。
• 各トピックグループに、提出契約のフィールドである topic_domain_key、topic_domain_title、topic_group_key、topic_group_title が含まれていること。
• アセットごとに候補を 1 件作成していないこと。
• イベント名／プロパティ名／メトリクス名をプロジェクトのセマンティックタイトルに昇格させていないこと。
• 各候補の resource_refs に、実際のアセット名／型／ID、またはパッケージ内の名称を結び付けていること。
• 各候補が、その意味、適用範囲、使用方法、対象外の事項を説明していること。
• 各候補の本文が、プロジェクトで使用されている自然言語で、業務上の定義、適用可能な質問、判断または計算のルール、Agent の使用方法、境界または例外を扱っていること。見出しの正確な文言は機械的な契約ではありません。
• 具体的な業務判断は判断または計算の内容に記載し、アセット名や件数は resource_refs、evidence、recommendation_reason に記載すること。セマンティック本文には含めません。
• アセット名や件数だけを変更して本文を使い回した候補がある場合、そのバッチはレビューに不合格となること。
• 各候補に、推薦理由を示す根拠の抜粋またはソースタイトルが含まれていること。
• 各候補が、Agent による業務上の質問の解釈、既定アセットの選択、またはプロジェクト全体に適用されるルールの適用方法を変えること。
• 各候補が、query-routing-v5.md に定められた根拠に基づく推薦種別のいずれかを宣言していること：QUERY_ROUTING、RECALL_SHORTCUT、ANALYSIS_PLAYBOOK。
• 数式、しきい値、状態、イベント、プロパティ、レポート、アセット名は、補足的な L1 の根拠であり、単独の候補ではないこと。
• ルートには意味のあるアセット選択の分岐、ショートカットには最小限のバンドルに加えて停止条件とフォールバック、プレイブックにはノートに裏付けられた経路、または構造から推定した推奨経路であることの明示が含まれていること。
• 提出前に、公開済みおよび無効化済みのセマンティクスを確認していること。無効化済みのセマンティクスは、再作成を抑止します。
• 未認証のアセットがルート、ショートカット、またはプレイブックを裏付けるのは、定義、作業単位の構造、使用状況、またはノートによる裏付けがある場合に限られます。エクスポートされたという理由だけで、プロジェクトの認定済みルールとして提示してはいけません。
• 根拠が乏しい場合は、候補を見送るか、確信度を下げて示すこと。根拠の弱い推薦を誇張してはいけません。

汎用抽出プロトコル

このプロトコルは、ゲーム、小売、金融、SaaS、運用、未知のプロジェクト領域で変更なく機能する必要があります。

1. テーマを決めずに、証拠を棚卸しします。認証済みと未認証のダッシュボード／レポートを分け、エクスポートの範囲と選択理由を記録し、既存のガバナンス対象のセマンティクスと、それを裏付ける L1 メタデータを区別します。
2. 実際に読み取った証拠だけから、セマンティックファミリーを特定します。次の分野横断的なディメンションは、あらかじめ答えとして用意するのではなく、質問として扱います。
   • ビジネスオブジェクト、状態、別名。
   • 分析対象と重複排除の粒度。
   • 指標、集計、分子、分母、変換。
   • 包含、除外、フィルターの範囲。
   • クエリ範囲、コホート期間、観測期間、最新性。
   • 単位、通貨、正規化、アトリビューション。
   • デフォルトのアセット選択とアセット間の関係。
   • 適用可能性、例外、競合の境界。
3. 各ファミリー内の定義のバリエーションを比較します。証拠から、権威あるバリエーションが1つだけだと分かる場合に限り、候補はデフォルトを示せます。バリエーションが競合する場合は、独自に標準を作り出さず、判別ルールまたは警告を示す必要があります。
4. セマンティックファミリーを把握してから、トピックドメインを設定します。ドメイン名にはプロジェクトで自然に使われるビジネス用語を用い、なぜその候補群をまとめて確認するのかを説明します。
5. その候補を取り除くと、将来のエージェントが誤ったビジネスオブジェクト、アセット、粒度、数式、範囲、単位、期間、または例外を選ぶ可能性が高くなる場合に限り、候補を生成します。
6. 本文内の主張ごとに、直接裏付ける証拠を特定します。アセット名と抜粋は resource_refs、evidence、recommendation_reason に保持し、再利用可能なビジネス知識は content に保持します。
7. 候補を、エージェントの動作の違いに基づいて比較します。同じ解釈と実行につながる候補は統合し、それぞれ独立して検索できる質問に答える候補は分割します。
8. 反例を確認します。提案するルールに反する可能性のある少数派の定義やアセットを調べます。裏付けのない結論は範囲を狭めるか、削除します。
9. 候補の文面を作る前に、証拠に裏付けられた問題の枠組みを作り、アセットの役割を割り当てます。query-routing-v5.md を使用し、候補数やアセットごとに1候補を網羅することを最適化の基準にしないでください。
10. 発見した問題の枠組みについて、ルーティング済み、ショートカット、プレイブック、定義のみ、証拠不十分の各処置を含む判断記録を保持します。

過学習防止ルール

• このスキルや CLI 生成コードに、顧客名、プロジェクト名、プロジェクト ID、アセット ID、想定されるトピック名、想定される候補名、想定される候補数を決して組み込まないでください。
• 固定された業界分類やキーワード辞書を出発点にしてはいけません。キーワードで証拠を探すのは、セマンティックファミリーを特定した後に限ります。キーワードによって結果を決めてはいけません。
• テストパッケージは評価サンプルであり、再利用可能なルールの情報源ではありません。無関係な他の領域にも適用できる根拠がある場合に限り、プロトコルを調整してください。
• 品質は、以前承認されたトピック一覧との一致ではなく、証拠による裏付けとエージェントの動作の変化で評価します。

ユーザー向けの推奨結果の表示

CLI の推奨結果をユーザーに表示する際、候補を単一の番号付きリストにまとめてはいけません。ユーザー向けの回答では、候補 JSON とフロントエンドのレビュー UI と同じ階層構造を使用する必要があります。

Project semantic recommendation scan completed

Summary:
- Topic domains: <N>
- Candidate semantics: <N>
- Validation: passed | failed

Topic domain: <topic_domain_title> (<candidate_count> semantics)
- [<semantic_type>] <candidate title>
  <one-sentence summary>
  Evidence: <asset title 1>, <asset title 2>, ...

ルール：

• 最初にトピックドメインを表示し、その下に候補を表示します。
• 各ドメインのセマンティック数を含めます。
• 各候補のセマンティック型、タイトル、短い要約、主要な証拠アセットのタイトルを含めます。
• CLI コマンドが topic_groups を返す場合は、表示順と件数にそのフィールドを直接使用します。
• 完全な JSON パスまたは送信コマンドは、人向けの要約とは分けて表示します。
• ユーザーが生の候補順を明示的に求めない限り、「1. セマンティック A 2. セマンティック B …」のようなフラットなリストを表示してはいけません。

出力規律

推奨結果を報告する際は、以下を含めてください。

• 実行したコマンド。
• 資産の範囲、エクスポート済み／認証済み／未認証の資産数、スナップショットのハッシュ。
• トピックのドメイン、各ドメインのセマンティック件数、ドメインごとに分類した候補タイトル。
• 各候補の根拠となる資産。
• 品質に関する警告（ある場合）。
• 問題フレームのカバー範囲と、却下された浅い機会に関する警告。
• 書き込み後の送信／レビュー／リリース ID。