skos-taxonomy

SKOS Taxonomist

SKOS を使用して運用分類体系を設計し、Panda とすべてのサブエージェントが作業を一貫して分類し、より適切なコンテキストを取得して、タグの乱立を避けられるようにします。

このスキルは理論ではなく実行を目的としています。概念を定義し、エージェントのデータを分類し、制約を検証して、分類体系のフィールドを Typesense に組み込みます。

使用するタイミング

次のいずれかに関係するリクエストで、このスキルを使用します。

• 「taxonomy」、「SKOS」、「controlled vocabulary」、「concept scheme」
• エージェントのやり取り、実行記録、ドキュメント、メモリー、イベント、タスクの分類
• concept_ids / primary_concept_id の契約の設計または改訂
• joelclaw の概念を別の語彙体系に対応付ける
• SKOS が必要か、よりシンプルなタグモデルで十分かの判断

主な成果

1. 安定した概念 URI を持つ、バージョン管理された SKOS 概念スキーム。
2. 決定論的な概念メタデータを生成するエージェント分類ルール。
3. 字句、ファセット、ハイブリッド検索に対応する Typesense フィールドマッピング。
4. 候補概念、エイリアスのずれ、非推奨化、マッピングに関するガバナンスルール。

SKOS の必須ルール（規範）

すべてのスキームで、次のルールに従います。

1. skos:Concept と skos:ConceptScheme は別個のクラスです。
2. skos:broader は推移的ではありません。推移的な上位プロパティの意味である skos:broaderTransitive を、閉包クエリに使用します。
3. リソースごとに、各言語タグにつき skos:prefLabel の値は最大 1 つです。
4. 同じリソースと言語形式において、skos:prefLabel、skos:altLabel、skos:hiddenLabel は相互に素です。
5. skos:related は skos:broaderTransitive と相互に素です。
6. マッピング関係は、スキーム間のリンクに使用します。skos:exactMatch は推移的なため、慎重に使用してください。
7. skos:closeMatch は意図的に推移的ではありません。
8. skos:Collection / skos:OrderedCollection はグループ化に使用し、skos:Concept とは相互に素です。

これらのいずれかに違反している場合は、展開前に作業を中断し、データを修正してください。

JoelClaw 運用スキーム（Workload v1）

ワークロード分類用に専用スキームを定義します。

• スキーム URI：joelclaw:scheme:workload:v1
• 分類体系のバージョン文字列：workload-v1
• 概念 URI のパターン：joelclaw:concept:<top-level>[:<subconcept>]
• 表記スタイル：大文字スネークケースまたはドット区切りの運用コード（安定かつ不変）

トップレベル概念（必須）

表記	URI	目的
PLATFORM	joelclaw:concept:platform	ランタイム／プラットフォームのインフラストラクチャとホスティング基盤
INTEGRATION	joelclaw:concept:integration	外部システムとの接続、API、Webhook、アダプター
TOOLING	joelclaw:concept:tooling	CLI／開発ツール、オペレーターコマンド、ローカル自動化
PIPELINE	joelclaw:concept:pipeline	Inngest／イベントのワークフロー、取り込みおよび処理チェーン
BUILD	joelclaw:concept:build	コード実装、テスト、CI/CD、パッケージング
KNOWLEDGE	joelclaw:concept:knowledge	ドキュメント、メモリー、分類体系、検索コンテキスト
COMMS	joelclaw:concept:comms	メッセージングチャネル、通知、エージェント／ユーザー間のコミュニケーション
OBSERVE	joelclaw:concept:observe	OTEL／ロギング／メトリクス／診断／信頼性テレメトリー
META	joelclaw:concept:meta	ガバナンス、ADR、ポリシー、ライフサイクルおよびプロセス管理

コア Turtle スケルトン

@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix jcw: <joelclaw:> .

jcw:scheme:workload:v1 a skos:ConceptScheme ;
  skos:prefLabel "JoelClaw Workload Taxonomy v1"@en ;
  skos:definition "Operational workload taxonomy for Panda and sub-agents."@en ;
  skos:hasTopConcept
    jcw:concept:platform,
    jcw:concept:integration,
    jcw:concept:tooling,
    jcw:concept:pipeline,
    jcw:concept:build,
    jcw:concept:knowledge,
    jcw:concept:comms,
    jcw:concept:observe,
    jcw:concept:meta .

jcw:concept:pipeline a skos:Concept ;
  skos:inScheme jcw:scheme:workload:v1 ;
  skos:topConceptOf jcw:scheme:workload:v1 ;
  skos:notation "PIPELINE" ;
  skos:prefLabel "Pipeline"@en ;
  skos:altLabel "workflow"@en, "event flow"@en ;
  skos:definition "Durable event-driven processing sequences."@en ;
  skos:scopeNote "Use for Inngest functions, ingest chains, and orchestration logic."@en ;
  skos:narrower jcw:concept:pipeline:ingest, jcw:concept:pipeline:enrichment ;
  skos:related jcw:concept:observe, jcw:concept:build .

エージェント分類契約

保存または取得の対象となるすべてのサブエージェント出力には、次の項目を含める必要があります。

• primary_concept_id（単一の正規概念 URI）
• concept_ids（順序付きリスト。最初に主概念、次に副概念）
• taxonomy_version
• concept_source（rules|llm|backfill|manual|fallback）
• classification_confidence（0～1 の浮動小数点数。任意ですが推奨）

推奨エンベロープ：

{
  "primary_concept_id": "joelclaw:concept:pipeline:ingest",
  "concept_ids": [
    "joelclaw:concept:pipeline:ingest",
    "joelclaw:concept:knowledge",
    "joelclaw:concept:observe"
  ],
  "taxonomy_version": "workload-v1",
  "concept_source": "rules",
  "classification_confidence": 0.88
}

分類手順

1. 候補ラベルを正規化します（trim、小文字化、スラッグ化、句読点の統一）。
2. prefLabel、次にaltLabel、最後にhiddenLabelのエイリアステーブルと照合します。
3. scopeNoteと隣接する概念（broader、related）を使用して曖昧さを解消します。
4. 1つの主要概念と、任意の副次概念を出力します。
5. 解決できない場合は、管理されたフォールバック概念に割り当て、未マッピングのラベルを記録します。
6. マッピング診断用のOTELメタデータ（mapped_count、unmapped_count、taxonomy_version）を出力します。

SKOS-XL（ラベルに第一級のメタデータが必要な場合）

ラベルオブジェクトにメタデータや関係性が必要な場合に限り、SKOS-XLを使用します。

• 出典情報を含む頭字語／略語の管理
• ラベルごとの出典の帰属
• ラベル単位の監査を伴う多言語／音訳のワークフロー
• ラベル間の関係（廃止用語 -> 置換用語）

ラベルが単なる同義語である場合は、コアSKOSラベルを使用してください。

SKOS-XLの例

@prefix skosxl: <http://www.w3.org/2008/05/skos-xl#> .
@prefix jcw: <joelclaw:> .

jcw:label:comms:imessage a skosxl:Label ;
  skosxl:literalForm "iMessage"@en .

jcw:concept:comms:imessage skosxl:altLabel jcw:label:comms:imessage .

外部語彙へのマッピング

マッピングプロパティは、1つのスキーム内ではなく、スキーム間で使用します。

• skos:exactMatch：意味が相互に置き換え可能（まれで、適用基準は厳格）
• skos:closeMatch：ほぼ同等。ほとんどの相互運用で安全な既定値
• skos:broadMatch / skos:narrowMatch：粒度の不一致
• skos:relatedMatch：スキームをまたぐ関連付け

内部のスキーム間マッピング例（Workload -> 既存のDocsスキーム）

@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix jcw: <joelclaw:> .
@prefix jcd: <jc:> .

jcw:concept:build skos:closeMatch jcd:docs:programming .
jcw:concept:observe skos:broadMatch jcd:docs:operations .
jcw:concept:knowledge skos:relatedMatch jcd:docs:education .

マッピングのガードレール：

1. closeMatchから始め、明示的なレビューを経た場合に限りexactMatchに引き上げます。
2. 複数のスキーム間でexactMatchを無条件に連鎖させないでください。
3. 推移的／対称的なマッピングの挙動によって生じる、推論上の衝突をレビューします。

コレクションと順序付きコレクション

階層構造を持たないグループ化にはコレクションを使用します。

• テーマ別のまとまり（例：すべてのコミュニケーションチャネル）にはskos:Collection
• 決定的な順序を持つ並び（例：エスカレーション段階）にはskos:OrderedCollection

コレクションで階層を表現しないでください。分類体系の構造にはbroader／narrowerを使用します。

@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix jcw: <joelclaw:> .

jcw:collection:comms-channels a skos:Collection ;
  skos:prefLabel "Comms channels"@en ;
  skos:member
    jcw:concept:comms:telegram,
    jcw:concept:comms:slack,
    jcw:concept:comms:imessage .

URIと表記法のポリシー（joelclaw:）

1. URIのローカル部分は、小文字のケバブケースまたはコロン区切りの運用パスにします。
2. skos:notationはリリース後に変更できません。
3. 概念URIを別の用途に再利用しないでください。古いURIを廃止し、マッピングを追加します。
4. 人が読む名称はIDではなく、ラベルに記述します。
5. 必要な場合を除き、スキームのバージョンは個々の概念URIではなく、スキームURIとメタデータに記述します。

推奨パターン：

• joelclaw:scheme:workload:v1
• joelclaw:concept:observe:otel
• joelclaw:collection:agent-lifecycle
• joelclaw:label:meta:adr

Typesense統合の契約

SKOSを意味情報の信頼できる唯一の情報源として扱い、Typesenseを検索実行環境として扱います。

フィールドマッピング

SKOS	Typesenseフィールド	型	備考
概念URI	id	string	正規識別子
skos:inScheme	scheme_id	string facet	スキーム／バージョンでフィルタリング
skos:notation	notation	string facet	運用コードの検索
skos:prefLabel	pref_label	string	主要な語彙形式
skos:altLabel	alt_labels	string[]	エイリアス検索／クエリ拡張
skos:hiddenLabel	hidden_labels	string[]	誤記／旧用語の復元
skos:definition	definition	string	長文形式の意味的コンテキスト
skos:scopeNote	scope_note	string	曖昧さ解消の指針
skos:broader	broader_ids	string[] facet	直接の親
skos:narrower	narrower_ids	string[] facet	直接の子
skos:related	related_ids	string[] facet	横断的な関連
マッピングプロパティ	exact_match_ids、close_match_idsなど	string[]	スキームをまたぐリンク
バージョン／ガバナンス	taxonomy_version、state	string facet	ロールアウト制御

検索対象となるエンティティ（ドキュメント、メモリ、イベント）については、次の項目も保存します。

• primary_concept_id
• concept_ids（string[]、ファセット化）
• concept_source
• taxonomy_version
• context_prefix、source_entity_id、evidence_tier、parent_evidence_id（該当する場合）

クエリパターン

分類候補の検索：

curl -s "http://localhost:8108/collections/taxonomy_concepts/documents/search?q=ingest+pipeline&query_by=pref_label,alt_labels,scope_note,definition&per_page=10" \
  -H "X-TYPESENSE-API-KEY: panda-typesense-key"

概念を条件とする検索：

curl -s "http://localhost:8108/collections/documents/documents/search?q=*&query_by=content&filter_by=concept_ids:=[joelclaw:concept:pipeline] && taxonomy_version:=workload-v1&per_page=20" \
  -H "X-TYPESENSE-API-KEY: panda-typesense-key"

運用上の注意：

1. 語彙クエリの条件なしでフィルタリングやファセット検索を行う場合は、q=* を使用します。
2. 高速なフィルタリングと診断のため、概念フィールドをファセットとして保持します。
3. 同義語は filter_by の値ではなく、q のトークンに対して適用されます。概念 ID は正規形式である必要があります。
4. 推移的な階層検索では、祖先の推移閉包を専用フィールド（例：ancestor_concept_ids）に事前計算して格納します。

ローカルアクセスのトラブルシューティング

localhost:8108 に接続できない場合は、まずポートフォワーディングを行います。

kubectl port-forward -n joelclaw svc/typesense 8108:8108

品質ゲートと検証

タクソノミーの変更をリリースする前に、次のチェックを実行します。

1. ラベルの整合性：
   • 概念ごとに、各言語の prefLabel が1つであること
   • prefLabel、altLabel、hiddenLabel が重複していないこと
2. 構造の整合性：
   • 各概念が、想定されるスキームのいずれか1つだけに属していること（または明示的に複数スキームを設計していること）
   • 意図しない階層の循環がないこと
   • broader と narrower に一貫性があること
3. マッピングの整合性：
   • マッピングリンクの対象が、外部スキームの概念に限られていること
   • exactMatch をレビューし、妥当性を確認していること
4. ランタイムの整合性：
   • concept_ids のカバレッジ目標を達成していること（新規レコードでは >=95%）
   • マッピングされていないラベルを OTEL で確認できること

推奨する運用プローブ：

• joelclaw otel search "concept_ids|primary_concept_id|taxonomy_version" --hours 24
• 広範な Brain／観測データの検索には joelclaw recall "<query>" を使用します。廃止されたメモリカテゴリのタクソノミーは、検索投影をフィルタリングしなくなりました。
• joelclaw docs search "<query>" --concept <concept-uri>

ガバナンスのワークフロー

1. 概念を正規概念ではなく、scopeNote を付けた candidate として提案します。
2. 既存のラベルやエイリアスとの衝突を確認します。
3. 分類ルールと検索フィルターへの影響を検証します。
4. レビューと使用実績の確認後にのみ、canonical に昇格させます。
5. URI を再利用せず、状態遷移とマッピングのヒントによって非推奨にします。
6. 変更には明示的にバージョンを付け（workload-v1 -> workload-v2）、移行メモを添えます。

アンチパターン

次のことは避けてください。

1. 「タグの寄せ集め」の増加：概念マッピングなしで検索に影響する自由形式のタグ。
2. 便宜的な同義語として exactMatch を使用すること。
3. コレクションへの所属を階層として扱うこと。
4. 検索ユースケースなしに深いツリーを構築すること。
5. scopeNote を省略し、後からプロンプトだけで下流の曖昧さを解消しようとすること。

SKOS が過剰な場合

次の条件をすべて満たす場合は、よりシンプルなタグ／列挙型モデルを使用します。

1. 安定したラベルが約30個未満である。
2. 階層やマッピングの要件がない。
3. 多言語対応やエイリアスのガバナンスが不要である。
4. ラベルがシステム間で再利用されない。
5. 検索品質が概念の意味に左右されない。

いずれかの条件が満たされなくなった場合は、拡張する前に SKOS へ移行します。

研究に基づく運用ガイダンス

エージェントのパイプラインでは、SKOS のメタデータを使用して検索品質を向上させます。

1. メタデータを考慮した検索パイプラインは、複数ホップ QA の精度を大幅に向上させる可能性があります（例：Multi-Meta-RAG ベンチマークで報告された F1／EM の向上）。
2. ドメイン IR の研究では、制御語彙と自由テキストの組み合わせは、一般にテキストのみのクエリと比べて適合率／再現率を向上させます。
3. joelclaw での実践的な示唆：分類の信頼度が高い場合は、語彙検索／ベクトル検索と概念フィルタリングまたは再ランキングのシグナルを常に組み合わせます。

参考資料

• W3C SKOS ホーム：https://www.w3.org/2004/02/skos/
• W3C SKOS リファレンス（規範）：https://www.w3.org/TR/skos-reference/
• W3C SKOS 入門：https://www.w3.org/TR/skos-primer/
• W3C SKOS ユースケースと要件：https://www.w3.org/TR/skos-ucr/
• Typesense コレクション API：https://typesense.org/docs/30.1/api/collections.html
• Typesense 検索 API：https://typesense.org/docs/30.1/api/search.html
• Typesense ベクトル検索：https://typesense.org/docs/30.1/api/vector-search.html
• Typesense 同義語：https://typesense.org/docs/30.1/api/synonyms.html
• Multi-Meta-RAG（メタデータ対応 RAG）：https://arxiv.org/abs/2406.13213
• 統制語彙とテキストクエリ拡張に関する研究（PubMed）：https://pubmed.ncbi.nlm.nih.gov/21893678/
• 統制語彙とテキスト検索を組み合わせた研究（PubMed）：https://pubmed.ncbi.nlm.nih.gov/23459623/