kairos-chain 3.9.4 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa87c57bf88c7f0f225793d049592120e2872deccda39c3eba3a3af059663dac
-  data.tar.gz: bf793a2f05c4e41bc43aa1f1d5a948985eeac39cee0c9c4c1c744d577e0c32ef
+  metadata.gz: 13fdfa15efd40f228b2fb789d51e1cbd722ce732bde40df4c8d25e5bf4108c56
+  data.tar.gz: 3aa43d1c26a56af6aa5c24e7ea9ca1d26a20f5c95984aec77f574874beeb810e
 SHA512:
-  metadata.gz: 27ea12fe7352161972a0e81754a8012ba03da6e03c4f1db6fd4f51bb60d599f0ebc1777c54a8d8169b138e308b035628666d80dcccdf95ad1b82f78fb047295c
-  data.tar.gz: 811bd5bf6f2339086196f1ea8edfe22371b3374bb1290ebbece3f8696c3a7c514baafbd24a1bf4cc7f7df0f8e29f0c825f1b36f2b22122345d3fcf704dab8141
+  metadata.gz: 80630f2c2488d3ab1b3864abc33f3f3711507c7ad1d6d166c21b06f33d8c044f51ec518ef22ae1bacc98e6c1a8d06dcff80afccb0d9b6b2b432dd38d7ad220ee
+  data.tar.gz: 27d701df365ec0c71b3b16b9190c78d0d590964192316d0d4a08218074ff289b5ca7edbd6fcca41311f9f0daeaed4b0a5ad46091bb36767afb1b2839e5dfab99

data/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.10.0] - 2026-03-31
+
+### Added
+
+- **introspection SkillSet** (v0.1.0) — New self-inspection SkillSet with 3 tools:
+  - `introspection_check`: Full inspection (L1 health + blockchain integrity + safety mechanisms + recommendations)
+  - `introspection_health`: L1 knowledge health scores using Synoptis TrustScorer (optional, falls back to staleness-only)
+  - `introspection_safety`: 4-layer safety mechanism visibility (L0 approval workflow, RBAC policies, agent safety gates, blockchain recording)
+- **Dream SkillSet L1 dedup + confidence scoring** (v0.2.1) — `dream_scan` now checks promotion candidates against existing L1 knowledge (name similarity + tag Jaccard overlap) and scores candidates with 3-dimension confidence (recurrence, tag consistency, session diversity). New `include_l1_dedup` parameter.
+- **`skills_promote` attestation integration** — Successful L2→L1 promotions now automatically issue Synoptis attestations (`claim: "promoted_from_l2"`, `actor_role: "automated"`). Graceful degradation when Synoptis is not loaded.
+- **`Safety.registered_policy_names`** — New thread-safe public API for introspecting registered RBAC policies. Replaces `instance_variable_get(:@policies)` pattern.
+
+### Fixed
+
+- **`system_upgrade` SkillSet-only install** — When specific SkillSet names are provided via `names` parameter but L0 templates are already up-to-date, `system_upgrade apply` now correctly installs/upgrades the requested SkillSets instead of returning "No upgrade needed". Previously, the L0 upgrade check (`UpgradeAnalyzer.upgrade_needed?`) gated all operations including SkillSet installs.
+
+### Design Process
+
+- Design reviewed: 2 rounds x 3 LLMs (Claude Opus 4.6, Codex GPT-5.4, Cursor Composer-2)
+- Implementation reviewed: 1 round x 3 LLMs per phase
+- 8 P0/P1 bugs found and fixed during design review (before any code was written)
+- Inspired by oh-my-claudecode analysis; independently designed with KairosChain philosophy
+
 ## [3.9.4] - 2026-03-30
 
 ### Added

data/lib/kairos_mcp/safety.rb

@@ -25,6 +25,12 @@ module KairosMcp
       @policy_mutex.synchronize { @policies[name.to_sym] }
     end
 
+    # Thread-safe list of registered policy names.
+    # Used by introspection SkillSet for safety visibility.
+    def self.registered_policy_names
+      @policy_mutex.synchronize { @policies.keys.map(&:to_s) }
+    end
+
     # For testing only
     def self.clear_policies!
       @policy_mutex.synchronize { @policies = {} }

data/lib/kairos_mcp/tools/skills_promote.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'json'
 require_relative 'base_tool'
 require_relative '../knowledge_provider'
 require_relative '../context_manager'
@@ -30,7 +31,8 @@ module KairosMcp
 
       def description
         'Promote knowledge between layers (L2→L1, L1→L0) with optional Persona Assembly for decision support. ' \
-        'Assembly generates a structured discussion from multiple perspectives before human decision.'
+        'Assembly generates a structured discussion from multiple perspectives before human decision. ' \
+        'For pattern detection and auto-scan, use dream_scan instead.'
       end
 
       def category
@@ -63,7 +65,7 @@ module KairosMcp
       end
 
       def related_tools
-        %w[context_save knowledge_update skills_evolve skills_audit]
+        %w[context_save knowledge_update skills_evolve skills_audit attestation_issue]
       end
 
       def input_schema
@@ -72,7 +74,7 @@ module KairosMcp
           properties: {
             command: {
               type: 'string',
-              description: 'Command: "analyze" (with assembly), "promote" (direct promotion), "status" (check requirements), or "suggest" (LLM suggests optimal personas for content)',
+              description: 'Command: "analyze" (with assembly), "promote" (direct promotion), "status" (check requirements), or "suggest" (LLM suggests optimal personas)',
               enum: %w[analyze promote status suggest]
             },
             source_name: {
@@ -122,7 +124,7 @@ module KairosMcp
             consensus_threshold: {
               type: 'number',
               description: 'Consensus threshold for early termination in discussion mode (default: 0.6 = 60%)'
-            }
+            },
           },
           required: %w[command]
         }
@@ -576,6 +578,9 @@ module KairosMcp
           # Track promotion event for state commit (this triggers auto-commit on promotion)
           track_promotion_change(from_layer: 'L2', to_layer: 'L1', skill_id: target_name, reason: reason)
 
+          # Issue attestation AFTER L1 exists
+          issue_promotion_attestation(target_name, reason)
+
           action = existing ? 'updated' : 'created'
           output = "## Promotion Successful\n\n"
           output += "**Target**: #{target_name} (L1)\n"
@@ -681,6 +686,27 @@ module KairosMcp
         end
       end
 
+      # Issue attestation after successful promotion
+      def issue_promotion_attestation(target_name, reason)
+        return unless synoptis_available?
+
+        invoke_tool('attestation_issue', {
+          'subject_ref' => "knowledge://#{target_name}",
+          'claim' => 'promoted_from_l2',
+          'evidence' => reason.to_s,
+          'actor_role' => 'automated'
+        })
+      rescue StandardError => e
+        # Synoptis may not be loaded — silently skip
+        warn "[SkillsPromote] Attestation skipped: #{e.message}"
+      end
+
+      def synoptis_available?
+        @registry && true
+      rescue StandardError
+        false
+      end
+
       # Track promotion event for state commit auto-commit
       def track_promotion_change(from_layer:, to_layer:, skill_id:, reason: nil)
         return unless SkillsConfig.state_commit_enabled?

data/lib/kairos_mcp/tools/system_upgrade.rb

@@ -240,6 +240,12 @@ module KairosMcp
         analyzer = UpgradeAnalyzer.new
         analyzer.analyze
 
+        # When specific SkillSet names are requested, skip L0 upgrade check
+        # and go directly to SkillSet install/upgrade
+        if names && !names.empty? && !analyzer.upgrade_needed?
+          return handle_skillset_only_install(names)
+        end
+
         unless analyzer.upgrade_needed?
           return text_content("No upgrade needed. Data directory is already up to date.")
         end
@@ -437,6 +443,32 @@ module KairosMcp
       # =====================================================================
       # skillsets — List all available SkillSets with install status
       # =====================================================================
+      # Install/upgrade specific SkillSets without requiring a full L0 upgrade.
+      # Called when names are specified but L0 templates are already up to date.
+      def handle_skillset_only_install(names)
+        ss_mgr = KairosMcp::SkillSetManager.new
+        ss_results = ss_mgr.upgrade_apply(names: names)
+
+        if ss_results.empty?
+          return text_content("No SkillSet changes needed for: #{names.join(', ')}")
+        end
+
+        output = "# SkillSet Install/Upgrade\n\n"
+        ss_results.each do |r|
+          if r[:action] == 'installed'
+            output += "  [INSTALLED] #{r[:name]} v#{r[:to]}\n"
+          else
+            output += "  [UPGRADED] #{r[:name]} v#{r[:from]} → v#{r[:to]} (#{r[:files_updated]} files)\n"
+          end
+        end
+        output += "\nNo L0 template changes needed.\n"
+        output += "Restart the MCP server to load new SkillSet tools.\n"
+
+        text_content(output)
+      rescue StandardError => e
+        text_content("SkillSet install failed: #{e.message}")
+      end
+
       def handle_skillsets
         ss_mgr = KairosMcp::SkillSetManager.new
         available = ss_mgr.available_skillsets

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.9.4"
+  VERSION = "3.10.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/skillsets/agent/tools/agent_start.rb

@@ -39,7 +39,9 @@ module KairosMcp
               properties: {
                 goal_name: {
                   type: 'string',
-                  description: 'Name of the goal (must exist as L1 knowledge or L2 context)'
+                  description: 'Name of the goal. Create it with context_save (L2) first. ' \
+                    'L1 knowledge is only for reusable goal templates. ' \
+                    'The agent searches L2 contexts first, then falls back to L1.'
                 },
                 max_cycles: {
                   type: 'integer',

data/templates/skillsets/dream/lib/dream/scanner.rb

@@ -25,8 +25,9 @@ module KairosMcp
         # @param scope [String] 'l2', 'l1', or 'all'
         # @param since_session [String, nil] Only scan sessions after this ID
         # @param include_archive_candidates [Boolean] Whether to detect stale L2
+        # @param include_l1_dedup [Boolean] Check promotion candidates against existing L1
         # @return [Hash] Structured scan result
-        def scan(scope: 'l2', since_session: nil, include_archive_candidates: true)
+        def scan(scope: 'l2', since_session: nil, include_archive_candidates: true, include_l1_dedup: true)
           result = {
             scope: scope,
             scanned_at: Time.now.iso8601,
@@ -38,7 +39,8 @@ module KairosMcp
 
           if %w[l2 all].include?(scope)
             scan_l2(result, since_session: since_session,
-                            include_archive_candidates: include_archive_candidates)
+                            include_archive_candidates: include_archive_candidates,
+                            include_l1_dedup: include_l1_dedup)
           end
 
           if %w[l1 all].include?(scope)
@@ -54,7 +56,7 @@ module KairosMcp
         # L2 scanning
         # ---------------------------------------------------------------
 
-        def scan_l2(result, since_session: nil, include_archive_candidates: true)
+        def scan_l2(result, since_session: nil, include_archive_candidates: true, include_l1_dedup: true)
           all_contexts = load_all_l2_contexts(since_session: since_session)
 
           # Partition: live contexts vs archived stubs
@@ -62,7 +64,20 @@ module KairosMcp
 
           # Promotion candidates: tag co-occurrence across sessions
           sessions_tags = build_sessions_tags(live)
-          result[:promotion_candidates] = detect_promotion_candidates(sessions_tags)
+          candidates = detect_promotion_candidates(sessions_tags, all_sessions_tags: sessions_tags)
+
+          # L1 dedup: mark candidates that already exist as L1 knowledge
+          if include_l1_dedup
+            kp = knowledge_provider
+            existing_l1 = kp ? kp.list : []
+            candidates.each do |candidate|
+              match = find_l1_match(candidate[:tag], Array(candidate[:tag]), existing_l1)
+              candidate[:already_in_l1] = !match.nil?
+              candidate[:l1_match] = match if match
+            end
+          end
+
+          result[:promotion_candidates] = candidates
 
           # Consolidation candidates: name token overlap
           result[:consolidation_candidates] = detect_consolidation_candidates(live)
@@ -132,8 +147,11 @@ module KairosMcp
         # Detect tags that recur across min_recurrence+ distinct sessions.
         #
         # @param sessions_tags [Hash] { session_id => { context_name => [tags] } }
-        # @return [Array<Hash>] promotion candidate hashes
-        def detect_promotion_candidates(sessions_tags)
+        # @param all_sessions_tags [Hash] same as sessions_tags (for scoring)
+        # @return [Array<Hash>] promotion candidate hashes with confidence scoring
+        def detect_promotion_candidates(sessions_tags, all_sessions_tags: nil)
+          all_sessions_tags ||= sessions_tags
+
           tag_sessions = Hash.new { |h, k| h[k] = Set.new }
 
           sessions_tags.each do |session_id, contexts|
@@ -148,12 +166,15 @@ module KairosMcp
                        .sort_by { |_tag, sids| -sids.size }
                        .first(@max_candidates)
                        .map do |tag, sids|
+            confidence = score_promotion_candidate(tag, sids, all_sessions_tags)
             {
               tag: tag,
               session_count: sids.size,
               sessions: sids.to_a,
               signal: 'tag_recurrence',
-              strength: sids.size.to_f / @min_recurrence
+              strength: sids.size.to_f / @min_recurrence,
+              confidence: confidence,
+              already_in_l1: false
             }
           end
 
@@ -274,6 +295,80 @@ module KairosMcp
           tags
         end
 
+        # ---------------------------------------------------------------
+        # L1 dedup and confidence scoring (migrated from skills_promote auto_scan)
+        # ---------------------------------------------------------------
+
+        # Find an existing L1 entry that matches a candidate by name or tag overlap.
+        #
+        # @param candidate_name [String] suggested/tag name of the candidate
+        # @param candidate_tags [Array<String>] tags for the candidate
+        # @param existing_l1 [Array<Hash>] list from KnowledgeProvider#list
+        # @return [String, nil] matching L1 entry name or nil
+        def find_l1_match(candidate_name, candidate_tags, existing_l1)
+          existing_l1.each do |entry|
+            # Name match (normalized substring ratio)
+            name_sim = name_similarity(candidate_name, entry[:name])
+            return entry[:name] if name_sim > 0.8
+
+            # Tag overlap (Jaccard on name tokens vs entry tags)
+            entry_tags = Array(entry[:tags]).to_set
+            candidate_set = candidate_tags.to_set
+            sim = candidate_set.empty? && entry_tags.empty? ? 0.0 : (candidate_set & entry_tags).size.to_f / (candidate_set | entry_tags).size.to_f
+            return entry[:name] if sim > 0.8
+          end
+          nil
+        end
+
+        # Compute name similarity using token-level Jaccard.
+        #
+        # @param a [String]
+        # @param b [String]
+        # @return [Float] 0.0..1.0
+        def name_similarity(a, b)
+          a_parts = a.to_s.split('_').to_set
+          b_parts = b.to_s.split('_').to_set
+          return 0.0 if a_parts.empty? && b_parts.empty?
+          (a_parts & b_parts).size.to_f / [a_parts.size, b_parts.size].max
+        end
+
+        # Score a promotion candidate across 3 dimensions:
+        #   - recurrence: how many sessions the tag appears in (max 40)
+        #   - tag_consistency: co-occurrence consistency across sessions (max 30)
+        #   - session_diversity: distinct sessions (max 30)
+        #
+        # @param tag [String] the recurring tag
+        # @param sessions [Set<String>] session IDs where this tag appears
+        # @param all_sessions_tags [Hash] { session_id => { context_name => [tags] } }
+        # @return [Integer] 0..100
+        def score_promotion_candidate(tag, sessions, all_sessions_tags)
+          # Recurrence: 3=10, 4=20, 5=30, 6+=40 (max 40 points)
+          recurrence_score = [[sessions.size - 2, 4].min * 10, 40].min
+          recurrence_score = [recurrence_score, 0].max
+
+          # Tag consistency: what fraction of sessions containing this tag
+          # also share the same co-occurring tags?
+          co_tags_per_session = sessions.map do |sid|
+            contexts = all_sessions_tags[sid] || {}
+            contexts.values.flatten.uniq.reject { |t| t == tag }
+          end.reject(&:empty?)
+
+          if co_tags_per_session.size >= 2
+            co_sets = co_tags_per_session.map(&:to_set)
+            intersection = co_sets.reduce(:&)
+            union = co_sets.reduce(:|)
+            tag_consistency = union.empty? ? 0.0 : intersection.size.to_f / union.size
+          else
+            tag_consistency = 0.0
+          end
+          tag_score = (tag_consistency * 30).round
+
+          # Session diversity: distinct sessions (max 30 points)
+          session_score = [[sessions.size - 1, 3].min * 10, 30].min
+
+          [recurrence_score + tag_score + session_score, 100].min
+        end
+
         # ---------------------------------------------------------------
         # Helpers
         # ---------------------------------------------------------------

data/templates/skillsets/dream/tools/dream_scan.rb

@@ -42,6 +42,10 @@ module KairosMcp
                 include_archive_candidates: {
                   type: 'boolean',
                   description: 'Whether to detect stale L2 contexts for archival. Default: true'
+                },
+                include_l1_dedup: {
+                  type: 'boolean',
+                  description: 'Check promotion candidates against existing L1 knowledge to mark duplicates. Default: true'
                 }
               },
               required: []
@@ -55,7 +59,8 @@ module KairosMcp
             scan_result = scanner.scan(
               scope: arguments['scope'] || config.dig('scan', 'default_scope') || 'l2',
               since_session: arguments['since_session'],
-              include_archive_candidates: arguments.fetch('include_archive_candidates', true)
+              include_archive_candidates: arguments.fetch('include_archive_candidates', true),
+              include_l1_dedup: arguments.fetch('include_l1_dedup', true)
             )
 
             # Record findings on blockchain if non-empty
@@ -131,7 +136,9 @@ module KairosMcp
               lines << "_No recurring patterns detected._"
             else
               promo.each do |c|
-                lines << "- **#{c[:tag]}**: #{c[:session_count]} sessions (strength: #{c[:strength].round(2)})"
+                dedup_marker = c[:already_in_l1] ? " [already in L1: #{c[:l1_match]}]" : ''
+                confidence_str = c[:confidence] ? " (confidence: #{c[:confidence]})" : ''
+                lines << "- **#{c[:tag]}**: #{c[:session_count]} sessions (strength: #{c[:strength].round(2)})#{confidence_str}#{dedup_marker}"
               end
             end
             lines << ""

data/templates/skillsets/introspection/config/introspection.yml

@@ -0,0 +1,4 @@
+introspection:
+  health:
+    staleness_days: 180
+  report_format: "markdown"

data/templates/skillsets/introspection/knowledge/introspection_guide/introspection_guide.md

@@ -0,0 +1,90 @@
+---
+title: Introspection Guide
+description: Usage guide for the introspection SkillSet — self-inspection, health scoring, and safety visibility
+version: "0.1.0"
+tags:
+  - introspection
+  - health
+  - safety
+  - blockchain
+  - maintenance
+---
+
+# Introspection Guide
+
+## Overview
+
+The introspection SkillSet provides self-inspection capabilities for KairosChain.
+It examines knowledge health, blockchain integrity, and safety mechanisms to produce
+actionable reports and recommendations.
+
+## Tools
+
+### introspection_check
+
+Full self-inspection combining all domains. Returns a consolidated report with
+recommendations.
+
+```
+introspection_check()                           # All domains, markdown format
+introspection_check(format: "json")             # JSON output
+introspection_check(domains: ["health"])        # Health only
+introspection_check(domains: ["blockchain"])    # Blockchain only
+```
+
+### introspection_health
+
+Focused L1 knowledge health scoring.
+
+```
+introspection_health()                          # All entries
+introspection_health(name: "my_knowledge")      # Single entry
+introspection_health(below_threshold: 0.5)      # Only unhealthy entries
+introspection_health(sort_by: "name")           # Sort alphabetically
+```
+
+### introspection_safety
+
+Safety mechanism visibility across all layers.
+
+```
+introspection_safety()    # Returns 4-layer safety report
+```
+
+## Health Scoring
+
+Health scores range from 0.0 (unhealthy) to 1.0 (healthy).
+
+When Synoptis TrustScorer is available:
+- **Trust score** (70% weight): Based on attestation count and quality
+- **Staleness score** (30% weight): Based on file modification time
+
+When TrustScorer is not available:
+- **Staleness score only** (100%): Linear decay over configurable threshold
+
+### Staleness Threshold
+
+Default: 180 days. Configure in `config/introspection.yml`:
+
+```yaml
+introspection:
+  health:
+    staleness_days: 90  # More aggressive freshness requirement
+```
+
+## Safety Layers
+
+The safety report covers four layers:
+
+1. **L0 Approval Workflow**: Whether Kairos DSL approval_workflow skill is loaded
+2. **Runtime RBAC**: Registered Safety policies (can_modify_l0, etc.)
+3. **Agent Safety Gates**: Autonomous mode limits from agent.yml
+4. **Blockchain Recording**: Chain integrity and block count
+
+## Recommendations
+
+The full check generates prioritized recommendations:
+
+- **CRITICAL**: Blockchain integrity failure
+- **HIGH**: Missing L0 approval workflow
+- **MEDIUM**: Low health scores on individual knowledge entries

data/templates/skillsets/introspection/lib/introspection/health_scorer.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module KairosMcp
+  module SkillSets
+    module Introspection
+      # HealthScorer calculates health scores for L1 knowledge entries.
+      #
+      # When Synoptis TrustScorer is available, health is a weighted composite
+      # of trust score (70%) and staleness score (30%). When TrustScorer is
+      # unavailable (Synoptis not loaded), health equals staleness only.
+      #
+      # Staleness is computed from File.mtime of the knowledge .md file,
+      # decaying linearly over a configurable threshold (default 180 days).
+      class HealthScorer
+        TRUST_WEIGHT = 0.70
+        STALENESS_WEIGHT = 0.30
+
+        def initialize(user_context: nil, config: {})
+          @user_context = user_context
+          @config = config
+          @trust_scorer = build_trust_scorer
+        end
+
+        # Score all L1 knowledge entries.
+        #
+        # @return [Hash] :overall_health, :entry_count, :trust_scorer_available, :entries
+        def score_l1
+          provider = ::KairosMcp::KnowledgeProvider.new(nil, user_context: @user_context)
+          summaries = provider.list
+
+          scored = summaries.map { |summary| score_entry_from_summary(summary, provider) }
+                           .sort_by { |e| e[:health_score] }
+
+          overall = scored.empty? ? 0.0 : (scored.sum { |e| e[:health_score] } / scored.size).round(4)
+
+          {
+            overall_health: overall,
+            entry_count: scored.size,
+            trust_scorer_available: !@trust_scorer.nil?,
+            entries: scored
+          }
+        end
+
+        # Score a single L1 knowledge entry by name.
+        #
+        # @param name [String] Knowledge entry name
+        # @return [Hash] :entry or :error
+        def score_single(name)
+          provider = ::KairosMcp::KnowledgeProvider.new(nil, user_context: @user_context)
+          entry = provider.get(name)
+          return { error: "Knowledge '#{name}' not found" } unless entry
+
+          {
+            entry: score_entry_from_skill_entry(entry),
+            trust_scorer_available: !@trust_scorer.nil?
+          }
+        end
+
+        private
+
+        # Score from a summary hash (from provider.list).
+        # Must call provider.get(name) to obtain SkillEntry with md_file_path.
+        def score_entry_from_summary(summary, provider)
+          skill_entry = provider.get(summary[:name])
+          if skill_entry
+            score_entry_from_skill_entry(skill_entry)
+          else
+            # Fallback: no SkillEntry found (shouldn't happen normally)
+            {
+              name: summary[:name],
+              health_score: 0.5,
+              trust_score: 0.0,
+              trust_details: {},
+              attestation_count: 0,
+              staleness_score: 0.5,
+              tags: summary[:tags]
+            }
+          end
+        end
+
+        # Score from a SkillEntry object (has md_file_path).
+        def score_entry_from_skill_entry(entry)
+          trust = if @trust_scorer
+                    @trust_scorer.calculate("knowledge://#{entry.name}")
+                  else
+                    { score: 0.0, details: {}, attestation_count: 0, active_count: 0 }
+                  end
+
+          staleness = calculate_staleness(entry)
+
+          # When TrustScorer unavailable, health = staleness only
+          health = if @trust_scorer
+                     (trust[:score] * TRUST_WEIGHT + staleness * STALENESS_WEIGHT).round(4)
+                   else
+                     staleness.round(4)
+                   end
+
+          {
+            name: entry.name,
+            health_score: health,
+            trust_score: trust[:score],
+            trust_details: trust[:details],
+            attestation_count: trust[:attestation_count] || 0,
+            staleness_score: staleness.round(4),
+            tags: entry.tags
+          }
+        end
+
+        # Calculate staleness score from file modification time.
+        # Returns 1.0 for freshly modified, decays to 0.0 over threshold days.
+        def calculate_staleness(entry)
+          md_path = entry.respond_to?(:md_file_path) ? entry.md_file_path : nil
+          return 0.5 unless md_path && File.exist?(md_path)
+
+          age_days = (Time.now - File.mtime(md_path)) / 86400.0
+          threshold = @config.dig('introspection', 'health', 'staleness_days') || 180
+          [1.0 - (age_days / threshold.to_f), 0.0].max
+        rescue StandardError
+          0.5
+        end
+
+        def build_trust_scorer
+          return nil unless defined?(::Synoptis::TrustScorer)
+          registry = ::Synoptis::Registry::FileRegistry.new(
+            storage_dir: File.join(::KairosMcp.storage_dir, 'synoptis')
+          )
+          ::Synoptis::TrustScorer.new(registry: registry)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/introspection/lib/introspection/safety_inspector.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module KairosMcp
+  module SkillSets
+    module Introspection
+      # SafetyInspector reports on all active safety mechanisms across layers:
+      # - L0: approval_workflow (Kairos DSL)
+      # - RBAC: registered Safety policies
+      # - Agent: autonomous mode safety gates from agent.yml
+      # - Blockchain: chain integrity and block count
+      class SafetyInspector
+        # Inspect all safety layers and return a structured report.
+        #
+        # @return [Hash] :layers with 4 sub-keys
+        def inspect_safety
+          {
+            layers: {
+              l0_approval_workflow: inspect_approval_workflow,
+              runtime_rbac: inspect_rbac_policies,
+              agent_safety_gates: inspect_agent_gates,
+              blockchain_recording: inspect_blockchain_health
+            }
+          }
+        end
+
+        private
+
+        def inspect_approval_workflow
+          if defined?(::Kairos) && ::Kairos.respond_to?(:skill)
+            skill = ::Kairos.skill(:approval_workflow)
+            {
+              present: !skill.nil?,
+              version: skill&.respond_to?(:version) ? skill.version : nil,
+              status: skill ? 'active' : 'not_loaded'
+            }
+          else
+            { present: false, status: 'kairos_not_available' }
+          end
+        end
+
+        def inspect_rbac_policies
+          names = ::KairosMcp::Safety.registered_policy_names
+          {
+            registered_count: names.size,
+            policies: names,
+            multiuser_active: names.include?('can_modify_l0')
+          }
+        end
+
+        def inspect_agent_gates
+          agent_config_path = File.join(::KairosMcp.skillsets_dir, 'agent', 'config', 'agent.yml')
+          if File.exist?(agent_config_path)
+            config = YAML.safe_load(File.read(agent_config_path)) || {}
+            autonomous = config['autonomous'] || {}
+            {
+              present: true,
+              max_cycles: autonomous['max_cycles'],
+              timeout: autonomous['timeout'],
+              max_llm_calls: autonomous['max_llm_calls'],
+              risk_budget: autonomous['risk_budget']
+            }
+          else
+            { present: false, status: 'agent_skillset_not_loaded' }
+          end
+        rescue StandardError => e
+          { present: false, error: e.message }
+        end
+
+        def inspect_blockchain_health
+          chain = ::KairosMcp::KairosChain::Chain.new
+          blocks = chain.chain
+          {
+            block_count: blocks.size,
+            last_recorded: blocks.last&.timestamp&.iso8601,
+            integrity: chain.valid?
+          }
+        rescue StandardError => e
+          { block_count: 0, integrity: false, error: e.message }
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/introspection/lib/introspection.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Introspection SkillSet loader
+# Loads all library classes for the introspection SkillSet.
+
+require_relative 'introspection/health_scorer'
+require_relative 'introspection/safety_inspector'

data/templates/skillsets/introspection/skillset.json

@@ -0,0 +1,17 @@
+{
+  "name": "introspection",
+  "version": "0.1.0",
+  "description": "Self-inspection and maintenance. Calculates knowledge health scores, checks blockchain integrity, and visualizes safety mechanisms.",
+  "author": "Masaomi Hatakeyama",
+  "layer": "L1",
+  "depends_on": [],
+  "provides": ["health_scoring", "integrity_check", "safety_visibility"],
+  "tool_classes": [
+    "KairosMcp::SkillSets::Introspection::Tools::IntrospectionCheck",
+    "KairosMcp::SkillSets::Introspection::Tools::IntrospectionHealth",
+    "KairosMcp::SkillSets::Introspection::Tools::IntrospectionSafety"
+  ],
+  "config_files": ["config/introspection.yml"],
+  "knowledge_dirs": ["knowledge/introspection_guide"],
+  "min_core_version": "3.9.0"
+}

data/templates/skillsets/introspection/tools/introspection_check.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+
+module KairosMcp
+  module SkillSets
+    module Introspection
+      module Tools
+        # Full self-inspection tool combining health, blockchain, and safety domains.
+        # Produces a consolidated report with recommendations.
+        class IntrospectionCheck < ::KairosMcp::Tools::BaseTool
+          def name
+            'introspection_check'
+          end
+
+          def description
+            'Full self-inspection: knowledge health scores, blockchain integrity, ' \
+            'and safety mechanism visibility. Uses Synoptis TrustScorer when available.'
+          end
+
+          def category
+            :introspection
+          end
+
+          def usecase_tags
+            %w[health blockchain safety introspection maintenance]
+          end
+
+          def related_tools
+            %w[introspection_health introspection_safety chain_verify]
+          end
+
+          def input_schema
+            {
+              type: 'object',
+              properties: {
+                domains: {
+                  type: 'array',
+                  items: { type: 'string', enum: %w[health blockchain safety] },
+                  description: 'Domains to inspect (default: all)'
+                },
+                format: {
+                  type: 'string',
+                  enum: %w[markdown json],
+                  description: 'Output format (default: markdown)'
+                }
+              }
+            }
+          end
+
+          def call(arguments)
+            domains = arguments['domains'] || %w[health blockchain safety]
+            fmt = arguments['format'] || 'markdown'
+
+            report = { inspected_at: Time.now.iso8601 }
+
+            if domains.include?('health')
+              report[:health] = health_scorer.score_l1
+            end
+
+            if domains.include?('blockchain')
+              report[:blockchain] = check_blockchain
+            end
+
+            if domains.include?('safety')
+              report[:safety] = safety_inspector.inspect_safety
+            end
+
+            report[:recommendations] = build_recommendations(report)
+
+            if fmt == 'json'
+              text_content(JSON.pretty_generate(report))
+            else
+              text_content(format_markdown(report))
+            end
+          end
+
+          private
+
+          def health_scorer
+            @health_scorer ||= HealthScorer.new(
+              user_context: @safety&.current_user,
+              config: load_config
+            )
+          end
+
+          def safety_inspector
+            @safety_inspector ||= SafetyInspector.new
+          end
+
+          def check_blockchain
+            chain = ::KairosMcp::KairosChain::Chain.new
+            valid = chain.valid?
+            blocks = chain.chain
+            {
+              valid: valid,
+              block_count: blocks.size,
+              latest_timestamp: blocks.last&.timestamp&.iso8601,
+              status: valid ? 'healthy' : 'INTEGRITY_FAILURE'
+            }
+          rescue StandardError => e
+            { valid: false, error: e.message, status: 'error' }
+          end
+
+          def build_recommendations(report)
+            recs = []
+
+            # Low health scores
+            if report[:health]
+              report[:health][:entries]&.each do |entry|
+                if entry[:health_score] < 0.4
+                  recs << {
+                    priority: 'medium',
+                    target: entry[:name],
+                    message: "Low health score (#{entry[:health_score]}). Consider updating or adding attestations."
+                  }
+                end
+              end
+            end
+
+            # Blockchain issues
+            if report[:blockchain] && !report[:blockchain][:valid]
+              recs << { priority: 'critical', target: 'blockchain', message: 'Blockchain integrity check failed.' }
+            end
+
+            # Safety gaps
+            if report[:safety]
+              unless report.dig(:safety, :layers, :l0_approval_workflow, :present)
+                recs << { priority: 'high', target: 'approval_workflow', message: 'L0 approval workflow not loaded.' }
+              end
+            end
+
+            recs
+          end
+
+          def load_config
+            config_path = File.join(
+              ::KairosMcp.skillsets_dir, 'introspection', 'config', 'introspection.yml'
+            )
+            return {} unless File.exist?(config_path)
+            YAML.safe_load(File.read(config_path)) || {}
+          rescue StandardError
+            {}
+          end
+
+          def format_markdown(report)
+            lines = []
+            lines << "# Introspection Report"
+            lines << ""
+            lines << "**Inspected at**: #{report[:inspected_at]}"
+            lines << ""
+
+            if report[:health]
+              lines << "## Knowledge Health"
+              lines << ""
+              lines << "- **Overall health**: #{report[:health][:overall_health]}"
+              lines << "- **Entry count**: #{report[:health][:entry_count]}"
+              lines << "- **TrustScorer available**: #{report[:health][:trust_scorer_available]}"
+              lines << ""
+
+              if report[:health][:entries]&.any?
+                lines << "| Name | Health | Trust | Staleness | Attestations |"
+                lines << "|------|--------|-------|-----------|--------------|"
+                report[:health][:entries].each do |e|
+                  lines << "| #{e[:name]} | #{e[:health_score]} | #{e[:trust_score]} | #{e[:staleness_score]} | #{e[:attestation_count]} |"
+                end
+                lines << ""
+              end
+            end
+
+            if report[:blockchain]
+              lines << "## Blockchain"
+              lines << ""
+              lines << "- **Valid**: #{report[:blockchain][:valid]}"
+              lines << "- **Block count**: #{report[:blockchain][:block_count]}"
+              lines << "- **Latest timestamp**: #{report[:blockchain][:latest_timestamp] || 'N/A'}"
+              lines << "- **Status**: #{report[:blockchain][:status]}"
+              lines << ""
+            end
+
+            if report[:safety]
+              lines << "## Safety Mechanisms"
+              lines << ""
+              report[:safety][:layers]&.each do |layer_name, layer_data|
+                lines << "### #{layer_name}"
+                layer_data.each { |k, v| lines << "- **#{k}**: #{v}" }
+                lines << ""
+              end
+            end
+
+            if report[:recommendations]&.any?
+              lines << "## Recommendations"
+              lines << ""
+              report[:recommendations].each do |rec|
+                lines << "- [#{rec[:priority].upcase}] **#{rec[:target]}**: #{rec[:message]}"
+              end
+              lines << ""
+            end
+
+            lines.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/introspection/tools/introspection_health.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module KairosMcp
+  module SkillSets
+    module Introspection
+      module Tools
+        # Calculate health scores for L1 knowledge entries.
+        # Uses Synoptis TrustScorer when available, falls back to staleness-only scoring.
+        class IntrospectionHealth < ::KairosMcp::Tools::BaseTool
+          def name
+            'introspection_health'
+          end
+
+          def description
+            'Calculate health scores for L1 knowledge entries. ' \
+            'Uses Synoptis TrustScorer when available, falls back to staleness-only scoring.'
+          end
+
+          def category
+            :introspection
+          end
+
+          def usecase_tags
+            %w[health knowledge staleness trust introspection]
+          end
+
+          def related_tools
+            %w[introspection_check knowledge_list]
+          end
+
+          def input_schema
+            {
+              type: 'object',
+              properties: {
+                name: { type: 'string', description: 'Specific L1 knowledge name (optional, omit for all)' },
+                sort_by: { type: 'string', enum: %w[score name], description: 'Sort order (default: score)' },
+                below_threshold: { type: 'number', description: 'Only show entries below this score (0.0-1.0)' }
+              }
+            }
+          end
+
+          def call(arguments)
+            scorer = HealthScorer.new(user_context: @safety&.current_user, config: load_config)
+            result = if arguments['name']
+                       scorer.score_single(arguments['name'])
+                     else
+                       scorer.score_l1
+                     end
+
+            # Filter
+            if arguments['below_threshold'] && result[:entries]
+              result[:entries].select! { |e| e[:health_score] < arguments['below_threshold'] }
+            end
+
+            # Sort
+            if arguments['sort_by'] == 'name' && result[:entries]
+              result[:entries].sort_by! { |e| e[:name] }
+            end
+
+            text_content(JSON.pretty_generate(result))
+          end
+
+          private
+
+          def load_config
+            config_path = File.join(
+              KairosMcp.skillsets_dir, 'introspection', 'config', 'introspection.yml'
+            )
+            return {} unless File.exist?(config_path)
+            YAML.safe_load(File.read(config_path)) || {}
+          rescue StandardError
+            {}
+          end
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/introspection/tools/introspection_safety.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module KairosMcp
+  module SkillSets
+    module Introspection
+      module Tools
+        # Visualize all active safety mechanisms across layers:
+        # L0 approval workflow, RBAC policies, agent safety gates, blockchain health.
+        class IntrospectionSafety < ::KairosMcp::Tools::BaseTool
+          def name
+            'introspection_safety'
+          end
+
+          def description
+            'Visualize all active safety mechanisms across layers: ' \
+            'L0 approval workflow, RBAC policies, agent safety gates, blockchain health.'
+          end
+
+          def category
+            :introspection
+          end
+
+          def usecase_tags
+            %w[safety rbac approval blockchain introspection]
+          end
+
+          def related_tools
+            %w[introspection_check chain_verify]
+          end
+
+          def input_schema
+            { type: 'object', properties: {} }
+          end
+
+          def call(_arguments)
+            inspector = SafetyInspector.new
+            result = inspector.inspect_safety
+            text_content(JSON.pretty_generate(result))
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kairos-chain
 version: !ruby/object:Gem::Version
-  version: 3.9.4
+  version: 3.10.0
 platform: ruby
 authors:
 - Masaomi Hatakeyama
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-30 00:00:00.000000000 Z
+date: 2026-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -299,6 +299,15 @@ files:
 - templates/skillsets/hestia/tools/meeting_publish_needs.rb
 - templates/skillsets/hestia/tools/philosophy_anchor.rb
 - templates/skillsets/hestia/tools/record_observation.rb
+- templates/skillsets/introspection/config/introspection.yml
+- templates/skillsets/introspection/knowledge/introspection_guide/introspection_guide.md
+- templates/skillsets/introspection/lib/introspection.rb
+- templates/skillsets/introspection/lib/introspection/health_scorer.rb
+- templates/skillsets/introspection/lib/introspection/safety_inspector.rb
+- templates/skillsets/introspection/skillset.json
+- templates/skillsets/introspection/tools/introspection_check.rb
+- templates/skillsets/introspection/tools/introspection_health.rb
+- templates/skillsets/introspection/tools/introspection_safety.rb
 - templates/skillsets/knowledge_creator/config/knowledge_creator.yml
 - templates/skillsets/knowledge_creator/knowledge/creation_guide/creation_guide.md
 - templates/skillsets/knowledge_creator/knowledge/quality_criteria/quality_criteria.md
@@ -462,7 +471,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: KairosChain - Self-referential MCP server for auditable skill self-management