skill-system-insight

スキルシステムのインサイト

互換性のための非推奨インターフェースです。observe/evolve の動作は現在、skill-system-soul が正式に担っていますが、マージ期間中に既存の insight ルート、ドキュメント、テストが壊れないよう、このスキルも引き続き利用できます。

ユーザーへの適応を実現する、統合された OBSERVE → EVOLVE エンジンです。

このスキルは、セッションを構造化された行動インサイト（「ファセット」）に変換し、そのファセットを使って二重マトリックスのソウル状態を維持します。また、定期的にソウルプロファイルとワークフローレシピを進化させます。すべてバージョン管理され、ロールバック可能です。

2 つのフェーズ、1 つのスキル

Phase 1 — OBSERVE
  Extract facets → Update matrix buffers → (optional) Trigger synthesis

Phase 2 — EVOLVE
  Read accumulated data → Plan evidence-backed changes → Apply with versioning → Snapshot for audit/rollback

フェーズ 1 では生のシグナルを生成します。フェーズ 2 では、それを利用して永続的な変更を行います。

進化のライフサイクルは、アリーナ比較ループを通じて実行できます。

session -> facets -> evolve proposals -> arena A/B -> merge suggestion

アリーナの段階では推奨事項のみを出力します。プロファイルの自動切り替えや変更の自動マージは行いません。

アーキテクチャ：ハイブリッド 3 層システム

Layer 1: Base Profile (balanced.md)
  - Static skeleton: section format + safety/quality defaults.

Layer 2: Dual Matrix (soul-state)
  - Personality Matrix (slow/stable): openness, directness, autonomy, rigor, warmth
  - Emotion Matrix (faster baseline): patience, enthusiasm, caution, empathy

Layer 3: Synthesized Profile (user.md)
  - Periodically regenerated from Layer 1 + Layer 2 + accumulated facets.
  - Every regeneration creates a versioned snapshot.

レイヤー 2 が信頼できる唯一の情報源です。レイヤー 3 は、読み取りやすいバージョン管理された投影です。

データモデル

• ファセット（セッションごとの抽出）：schema/facet.yaml
• ソウル状態（二重マトリックス + カウンター／バッファー）：schema/soul-state.yaml
• 進化プラン（提案された変更）：schema/evolution-plan.yaml
• 進化スナップショット（バージョン管理されたアーティファクト）：schema/evolution-snapshot.yaml

ストレージでは、Postgres の agent_memories テーブルと型付きサブテーブルを使用します。

• ファセット：memory_type='episodic'、category='insight-facet' → 型付きテーブル：insight_facets
• ソウル状態：memory_type='semantic'、category='soul-state' → 型付きテーブル：soul_states
• 進化スナップショット：memory_type='episodic'、category='evolution-snapshot' → 型付きテーブル：evolution_snapshots

型付き関数（型付きテーブルと agent_memories の両方に二重書き込み）：

• insert_insight_facet(user, session_id, yaml, ...) → ファセットを保存します
• upsert_soul_state(user, yaml, personality, emotion, ...) → ソウル状態を保存／更新します
• get_soul_state(user) → soul_states から読み取ります
• get_recent_facets(user, limit) → insight_facets から読み取ります
• insert_evolution_snapshot(user, version_tag, target, ...) → バージョン管理されたスナップショットを保存します
• get_evolution_history(user, limit) → evolution_snapshots から読み取ります

フェーズ 1：OBSERVE パイプライン

Trigger (manual or suggested) → Extract Facet → Update Matrix → (optional) Synthesize Profile

参照：

• ファセット抽出プロンプト：prompts/facet-extraction.md
• ソウル統合プロンプト：prompts/soul-synthesis.md
• 抽出手順：scripts/extract-facets.md
• マトリックス更新アルゴリズム：scripts/update-matrix.md
• プロファイル再生成手順：scripts/synthesize-profile.md

起動方法（OBSERVE）

これは手動のワークフローです。

• ユーザーは「insight」「extract facets」「learn my preferences」「update my profile」と明示的に依頼できます。
• ルーターの提案パターン（簡潔で、押しつけがましくない表現）：
  • 「このセッションから学習するため、インサイト処理を実行しますか？（ファセットを保存し、マトリックスを更新する場合があります）」

ユーザーが依頼するか、同意した場合は、次の手順を実行します。

1. scripts/extract-facets.md
2. scripts/update-matrix.md
3. 統合のトリガーが発生した場合：scripts/synthesize-profile.md

フェーズ 2：EVOLVE パイプライン

Trigger (manual or scheduled) → Read facets + matrix → Plan evolution → Safety check → Apply → Snapshot

参照：

• 進化計画プロンプト：prompts/evolution-planning.md
• レシピ進化プロンプト：prompts/recipe-evolution.md
• 臨床的な組織レビューのプロンプト：prompts/clinical-organism-review.md
• ソウル進化手順：scripts/evolve-soul.md
• レシピ進化手順：scripts/evolve-recipes.md
• バージョン一覧：scripts/list-versions.md
• ロールバック手順：scripts/rollback.md

起動方法（EVOLVE）

• ユーザーは「evolve my profile」「evolve recipes」「list versions」「rollback to v2」と依頼できます。
• OBSERVE フェーズ中に統合のトリガーが発生すると、自動的に起動します。

バージョンタグ

形式：v{N}_{target}_{timestamp} 例：v3_soul_20260211

アルゴリズム：同じユーザーとターゲットに対して、N = 1 + max(existing N) とします。該当するものがない場合は N=1 から始めます。

臨床的な有機体レビュー（適合性の視点）

Insight に、BH/SK ボディマップのトリアージ用の適合性確認手順 clinical-organism-review が追加されました。

この手順では、次の必須フィールドを含むレビュー行が出力されます。

• body_part、technical_surface、tissue_class
• maturity（mature | prototype | embryonic | waste | retired）
• current_pain、evidence
• disposition（keep | grow | merge | retire | archive | excrete | bundle）
• owner、close_gate

厳守事項：診断は進捗ではありません。封じ込め＋修復＋検証を伴わない問題の発見は、すべて close_gate=pain_mapped のままにしてください。

使用方法：prompts/clinical-organism-review.md

書き込み先

• 進化スナップショット → Postgres（evolution_snapshots + agent_memories）
• ソウルプロファイル（ファイルシステム）→ ../skill-system-soul/profiles/<user>.md
• ワークフローレシピ（ファイルシステム）→ ../skill-system-workflow/recipes/*.yaml

設定

すべてのランタイム設定（レート制限、しきい値、ステップサイズ、承認ゲート）は config/insight.yaml にあります。

設定ファイルが唯一の信頼できる情報源です。 以下の値はドキュメント用のデフォルト値です。異なる場合は、config/ の設定が優先されます。

参照：../../config/insight.yaml

制約（必須）

透明性

学んだこととその理由を、常に説明してください。

• ファセットには、具体的な出来事に結び付いた証拠文字列を含めてください。
• マトリックスを更新する際は、適用した調整ごとに、その背景を説明する短い文を追加してください。
• 進化に関する変更にはすべて、ファセットまたは状態コンテキストに基づく証拠文字列を含めてください。

レート制限（デフォルト値 — config/insight.yaml を参照）

• OBSERVE：ユーザーごとに、ローリング24時間あたり最大 observe.max_facets_per_day 個のファセットを記録できます。
  • 上限を超えた場合：記録する予定だった内容を要約し、記録するセッションを1つ選ぶようユーザーに尋ねてください。
• EVOLVE：ユーザーごとに、1日あたり最大 evolve.max_passes_per_day 回の進化パスを実行できます（すべての対象を合算）。
  • 最新の evolution-snapshot の日付を制限の基準として使用してください。

信頼度のしきい値（デフォルト値 — config/insight.yaml を参照）

1回の観察だけでマトリックスの値を変更しないでください。

• しきい値：同じ方向を示す observe.confidence_threshold+ 件の類似観察。
• 性格のステップサイズ：条件を満たす調整ごとに +/- observe.personality_step。
• 感情ベースラインのステップサイズ：条件を満たす調整ごとに +/- observe.emotion_step。

テスト可能性と説明可能性を確保するため、蓄積量はバッファーで追跡します。

安全性（進化）

• ソウルプロファイルから中核的な安全制約を削除することはできません。
• 進化後のプロファイルには、正直な不確実性の表明、権威の捏造をしないこと、有害または違法な指示の拒否を維持する必要があります。
• 大幅な変更（いずれかの次元の変化が evolve.approval_drift_threshold を超える場合）には、適用前にユーザーの明示的な承認が必要です。

レイヤー1とレイヤー3の配置先

• ベースプロファイル（レイヤー1）：../skill-system-soul/profiles/balanced.md
• 合成されたユーザープロファイル（レイヤー3）：../skill-system-soul/profiles/<user>.md

合成手順では、次の6セクション形式を維持します。

1. アイデンティティ
2. 意思決定のヒューリスティクス
3. コミュニケーションスタイル
4. 品質基準
5. ツールの好み
6. アンチパターン

ストレージパターン（agent_memories）

SQLテンプレートの例：

-- Store a facet
SELECT store_memory(
  'episodic', 'insight-facet',
  ARRAY['session:ses_xxx', 'user:arthu'],
  'Session Facet: <brief_summary>',
  '<full facet YAML as text>',
  '{"session_type": "...", "outcome": "..."}',
  'insight-agent', 'ses_xxx', 5.0
);

-- Store/update matrix state
SELECT store_memory(
  'semantic', 'soul-state',
  ARRAY['user:arthu', 'matrix'],
  'Soul State: arthu',
  '<full soul-state YAML as text>',
  '{"total_insights": 0, "last_updated": "..."}',
  'insight-agent', NULL, 9.0
);

-- Store evolution snapshot (typed — dual-writes to agent_memories)
SELECT insert_evolution_snapshot(
  '<user>', '<version_tag>', '<target>', '<trigger>',
  '<changes JSONB>', '<snapshot_data>', '<full YAML>',
  NULL, 'insight-agent'
);

-- Query recent facets
SELECT * FROM search_memories('insight-facet user:arthu', NULL, NULL, NULL, NULL, 0.0, 50);

-- List evolution history
SELECT * FROM get_evolution_history('<user>', 50);

運用上の注意

• ファセットの抽出は、1回のパスで完了できるようにしてください。具体的な証拠で調整を正当化できない場合は、調整を提案しないでください。
• ユーザーが中国語でコミュニケーションを取ることがあります。これは性格の次元ではなく、慣れやすさを示すシグナルとして扱ってください。
• 値は [0.0, 1.0] の範囲に制限してください。

{
  "schema_version": "2.0",
  "id": "skill-system-insight",
  "version": "2.2.0",
  "capabilities": [
    "insight-issue-routing", "insight-session-facets", "insight-extract", "insight-matrix-update", "insight-synthesize",
    "evolution-proposal-draft",
    "evolution-arena-loop",
    "clinical-organism-review",
    "evolution-soul", "evolution-recipes", "evolution-list", "evolution-rollback"
  ],
  "effects": ["db.read", "db.write", "fs.read", "fs.write"],
  "operations": {
    "route-issue-draft": {
      "description": "Route findings into a draft issue target based on tags/category without creating issues.",
      "input": {
        "finding": { "type": "object", "required": true, "description": "Finding payload with tags/category/evidence/impact/suggested_direction" },
        "project_repo": { "type": "string", "required": true, "description": "Current project repository owner/name" },
        "skill_system_repo": { "type": "string", "required": true, "description": "Skill-system repository owner/name" }
      },
      "output": {
        "description": "Draft routing payload",
        "fields": { "status": "ok | error", "target_repo": "string", "draft_command": "string" }
      },
      "entrypoints": {
        "agent": "Use scripts/insight_bundle_b012.py route-issue-draft"
      }
    },
    "extract-session-facets": {
      "description": "Session-end facet extraction to soul-state memories via mem.py DB path or pending fallback.",
      "input": {
        "user": { "type": "string", "required": true, "description": "User handle" },
        "session_id": { "type": "string", "required": true, "description": "Session id" },
        "facets": { "type": "array", "required": true, "description": "Facet entries: {dimension, value, confidence, evidence}" }
      },
      "output": {
        "description": "Extraction and storage summary",
        "fields": { "status": "ok | blocked | error", "stored_count": "integer", "skipped_low_confidence": "integer", "skipped_rate_limit": "integer" }
      },
      "entrypoints": {
        "agent": "Use scripts/insight_bundle_b012.py extract-session-facets"
      }
    },
    "evolve-proposals": {
      "description": "Generate non-destructive evolution proposals from soul-state facets with daily-pass safety.",
      "input": {
        "user": { "type": "string", "required": true, "description": "User handle" }
      },
      "output": {
        "description": "Proposal-only evolve output",
        "fields": { "status": "ok | blocked | error", "proposals": "array", "reason": "string" }
      },
      "entrypoints": {
        "agent": "Use scripts/insight_bundle_b012.py evolve-proposals"
      }
    },
    "evolve-arena-loop": {
      "description": "Run proposal -> arena -> merge-suggestion flow using current profile versus mutated proposal candidates.",
      "input": {
        "user": { "type": "string", "required": true, "description": "User handle" },
        "task": { "type": "string", "required": true, "description": "Task label" },
        "current_profile": { "type": "string", "required": true, "description": "Current active profile" },
        "proposals": { "type": "array", "required": true, "description": "Evolution proposals to evaluate" },
        "metrics": { "type": "object", "required": true, "description": "Per-candidate arena metrics" }
      },
      "output": {
        "description": "Arena and merge suggestion report",
        "fields": { "arena_runs": "array", "merge_suggestions": "array", "auto_merge": "false" }
      },
      "entrypoints": {
        "agent": "Use scripts/insight_bundle_b012.py evolve-arena-loop"
      }
    },
    "clinical-organism-review": {
      "description": "Classify BH/SK surfaces with maturity/disposition and repair-oriented close gates.",
      "input": {
        "review_scope": { "type": "string", "required": true, "description": "Review target label such as sk, bh, or bundle-id" },
        "surfaces": { "type": "array", "required": true, "description": "Reviewed surfaces with evidence and proposed dispositions" },
        "evidence_sources": { "type": "array", "required": false, "description": "Optional source artifacts or body-map references" }
      },
      "output": {
        "description": "Clinical review rows with close gate status",
        "fields": { "status": "ok | blocked | error", "rows": "array", "closeable_rows": "integer", "pain_mapped_rows": "integer" }
      },
      "entrypoints": {
        "agent": "Follow prompts/clinical-organism-review.md"
      }
    },
    "extract-facets": {
      "description": "Extract a per-session facet from transcript. Rate limited to 3/24h per user.",
      "input": {
        "session_id": { "type": "string", "required": true, "description": "Session to analyze" },
        "user": { "type": "string", "required": true, "description": "User handle" }
      },
      "output": {
        "description": "Facet YAML stored to agent_memories",
        "fields": { "status": "ok | error", "memory_id": "integer" }
      },
      "entrypoints": {
        "agent": "Follow scripts/extract-facets.md procedure"
      }
    },
    "update-matrix": {
      "description": "Update dual matrix from stored facet with confidence gating.",
      "input": {
        "user": { "type": "string", "required": true, "description": "User handle" }
      },
      "output": {
        "description": "Updated soul-state YAML stored to agent_memories",
        "fields": { "status": "ok | error", "values_changed": "boolean" }
      },
      "entrypoints": {
        "agent": "Follow scripts/update-matrix.md procedure"
      }
    },
    "synthesize-profile": {
      "description": "Regenerate Layer 3 Soul profile from matrix + recent facets. Creates versioned snapshot.",
      "input": {
        "user": { "type": "string", "required": true, "description": "User handle" }
      },
      "output": {
        "description": "User profile written to skill-system-soul/profiles/<user>.md with version snapshot",
        "fields": { "status": "ok | error", "profile_path": "string", "version_tag": "string" }
      },
      "entrypoints": {
        "agent": "Follow scripts/synthesize-profile.md then scripts/evolve-soul.md snapshot step"
      }
    },
    "evolve-soul": {
      "description": "Evolve soul profile from accumulated insight data. Creates versioned snapshot.",
      "input": {
        "user": { "type": "string", "required": true, "description": "User handle" }
      },
      "output": {
        "description": "Evolution result with version tag",
        "fields": { "version_tag": "string", "changes": "array", "profile_path": "string" }
      },
      "entrypoints": {
        "agent": "Follow scripts/evolve-soul.md procedure"
      }
    },
    "evolve-recipes": {
      "description": "Evolve workflow recipes based on effectiveness data from insight facets.",
      "input": {
        "user": { "type": "string", "required": true, "description": "User handle" }
      },
      "output": {
        "description": "Recipe evolution result with version tag",
        "fields": { "version_tag": "string", "recipes_changed": "array" }
      },
      "entrypoints": {
        "agent": "Follow scripts/evolve-recipes.md procedure"
      }
    },
    "list-versions": {
      "description": "List all evolution snapshots for a user.",
      "input": {
        "user": { "type": "string", "required": true },
        "target": { "type": "string", "required": false, "description": "Filter: soul | recipe | all" }
      },
      "output": {
        "description": "Array of version snapshots",
        "fields": { "versions": "array of {tag, target, timestamp, summary}" }
      },
      "entrypoints": {
        "agent": "Follow scripts/list-versions.md procedure"
      }
    },
    "rollback": {
      "description": "Restore a previous evolution version.",
      "input": {
        "user": { "type": "string", "required": true },
        "version_tag": { "type": "string", "required": true, "description": "Version tag to restore" }
      },
      "output": {
        "description": "Rollback result",
        "fields": { "status": "ok | error", "restored_from": "string" }
      },
      "entrypoints": {
        "agent": "Follow scripts/rollback.md procedure"
      }
    }
  },
  "stdout_contract": {
    "last_line_json": true,
    "note": "The b012 helper script emits pretty-printed JSON to stdout for routing, facet extraction, and evolve proposals."
  }
}