kairos-chain 3.9.2 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58adf58a025748f0645e1933fc19c3fab811c68eb459d2f5a8a152417146c386
-  data.tar.gz: 1547a6b41b36061550ea60709eca097778500344b18f00849da26a47ed70397f
+  metadata.gz: 13fdfa15efd40f228b2fb789d51e1cbd722ce732bde40df4c8d25e5bf4108c56
+  data.tar.gz: 3aa43d1c26a56af6aa5c24e7ea9ca1d26a20f5c95984aec77f574874beeb810e
 SHA512:
-  metadata.gz: dcb1eb4a44279b9d0c94a61b47093d95b2d5f997d9b6ec3850424a2c9d11e26aeb75a4d1a04cc67e5848ceee4638b350233489f7b1f76d4acf3f16852a4bcd68
-  data.tar.gz: a10800df40fd5105ca2f84c21350a89d5ab4e2c3adf91cc41ac288dc2695a01141a4e96ae6df346b7613d9c03fdc5c0aa0afe1571ed269fc843d595f800ba3f2
+  metadata.gz: 80630f2c2488d3ab1b3864abc33f3f3711507c7ad1d6d166c21b06f33d8c044f51ec518ef22ae1bacc98e6c1a8d06dcff80afccb0d9b6b2b432dd38d7ad220ee
+  data.tar.gz: 27d701df365ec0c71b3b16b9190c78d0d590964192316d0d4a08218074ff289b5ca7edbd6fcca41311f9f0daeaed4b0a5ad46091bb36767afb1b2839e5dfab99

data/CHANGELOG.md

@@ -4,6 +4,50 @@ 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
+
+- **Permission advisory on claude_code fallback** — When the agent falls back
+  to the `claude_code` LLM provider (API key missing), it now checks if a
+  `PreToolUse` hook is configured in `.claude/settings.json` for the MCP server.
+  If not, a one-time `permission_advisory` is included in the `agent_step`
+  response with the exact hook configuration needed for uninterrupted
+  autonomous operation. The advisory is suggest-only and never modifies
+  user settings.
+
+## [3.9.3] - 2026-03-30
+
+### Fixed
+
+- **act_summary always 'failed'** — `autoexec_run` `internal_execute` mode
+  returns `outcome: "internal_execute_complete"` but `agent_step` checked
+  `run_parsed['status'] == 'ok'` (always nil). Changed to check
+  `outcome.end_with?('_complete')`.
+
 ## [3.9.2] - 2026-03-30
 
 ### Fixed

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.2"
+  VERSION = "3.10.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/skillsets/agent/lib/agent/cognitive_loop.rb

@@ -17,6 +17,7 @@ module KairosMcp
           @caller = caller_tool
           @session = session
           @fallback_attempted = false
+          @fallback_advisory_shown = false
           @total_calls = 0
         end
 
@@ -167,6 +168,7 @@ module KairosMcp
               next
             end
 
+            check_permission_advisory(fallback)
             return retry_parsed
           end
 
@@ -187,6 +189,72 @@ module KairosMcp
           false
         end
 
+        # Check if Claude Code PreToolUse hook is configured for the MCP server.
+        # If not, record a one-time advisory on the session so the user knows
+        # how to avoid permission prompts during autonomous operation.
+        def check_permission_advisory(provider)
+          return unless provider == 'claude_code'
+          return if @fallback_advisory_shown
+          return if claude_hook_configured?
+
+          @fallback_advisory_shown = true
+          mcp_name = detect_mcp_server_name
+          return unless mcp_name  # Can't advise without knowing the server name
+
+          matcher = "mcp__#{mcp_name}__*"
+
+          advisory = <<~MSG.strip
+            Claude Code fallback activated — using your Claude Code subscription instead of API.
+            For uninterrupted autonomous operation, a PreToolUse hook for "#{matcher}" is needed.
+
+            To auto-apply this setting, re-run agent_step with apply_permission_hook: true:
+              agent_step(session_id: "#{@session.session_id}", action: "approve", apply_permission_hook: true)
+
+            This auto-approves only #{mcp_name} MCP tools. Bash, file edits, and other tools still require confirmation.
+          MSG
+
+          @session.permission_advisory = advisory
+        end
+
+        def claude_hook_configured?
+          mcp_name = detect_mcp_server_name
+          return false unless mcp_name
+
+          matcher = "mcp__#{mcp_name}__*"
+          settings_candidates.each do |path|
+            next unless File.exist?(path)
+            settings = JSON.parse(File.read(path))
+            hooks = settings.dig('hooks', 'PreToolUse') || []
+            return true if hooks.any? { |h| h['matcher'] == matcher }
+          end
+          false
+        rescue StandardError
+          false
+        end
+
+        # Detect MCP server name from Claude Code settings.
+        # Scans project-level and global settings for mcpServers entries
+        # whose command/args include 'kairos-chain'.
+        def detect_mcp_server_name
+          settings_candidates.each do |path|
+            next unless File.exist?(path)
+            settings = JSON.parse(File.read(path))
+            (settings['mcpServers'] || {}).each do |name, config|
+              cmd_parts = Array(config['command']) + Array(config['args'])
+              return name if cmd_parts.any? { |part| part.to_s.include?('kairos-chain') }
+            end
+          end
+          nil
+        rescue StandardError
+          nil
+        end
+
+        def settings_candidates
+          project = File.join(Dir.pwd, '.claude', 'settings.json')
+          global = File.join(Dir.home, '.claude', 'settings.json')
+          [project, global]
+        end
+
         def extract_json(content)
           JSON.parse(content)
           content

data/templates/skillsets/agent/lib/agent/session.rb

@@ -9,6 +9,7 @@ module KairosMcp
       class Session
         attr_reader :session_id, :mandate_id, :goal_name, :invocation_context,
                     :state, :cycle_number, :config, :autonomous
+        attr_accessor :permission_advisory
 
         def initialize(session_id:, mandate_id:, goal_name:, invocation_context:, config:,
                        autonomous: false)

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/agent/tools/agent_step.rb

@@ -52,6 +52,10 @@ module KairosMcp
                 feedback: {
                   type: 'string',
                   description: 'Feedback for "revise" action (optional)'
+                },
+                apply_permission_hook: {
+                  type: 'boolean',
+                  description: 'Apply the suggested PreToolUse hook to .claude/settings.json (requires prior permission_advisory)'
                 }
               },
               required: %w[session_id action]
@@ -66,6 +70,11 @@ module KairosMcp
             session = Session.load(session_id)
             return error_result("Session not found: #{session_id}") unless session
 
+            if arguments['apply_permission_hook']
+              result = apply_permission_hook
+              return text_content(JSON.generate(result)) unless result['status'] == 'ok'
+            end
+
             case action
             when 'stop'
               handle_stop(session)
@@ -269,12 +278,14 @@ module KairosMcp
             result = run_act_reflect_internal(session)
             session.update_state('checkpoint')
             session.save
-            text_content(JSON.generate({
+            response = {
               'status' => 'ok', 'session_id' => session.session_id,
               'state' => 'checkpoint',
               'act_summary' => result.dig(:act, 'summary') || 'completed',
               'reflect' => result[:reflect]
-            }))
+            }
+            response['permission_advisory'] = session.permission_advisory if session.permission_advisory
+            text_content(JSON.generate(response))
           end
 
           # ---- AUTONOMOUS LOOP ----
@@ -423,7 +434,7 @@ module KairosMcp
                      else 'completed'
                      end
 
-            text_content(JSON.generate({
+            response = {
               'status' => status,
               'session_id' => session.session_id,
               'state' => session.state,
@@ -438,7 +449,9 @@ module KairosMcp
                   'confidence' => clamp_confidence(r.dig(:reflect, 'confidence')),
                   'remaining_count' => Array(r.dig(:reflect, 'remaining')).size }
               }
-            }))
+            }
+            response['permission_advisory'] = session.permission_advisory if session.permission_advisory
+            text_content(JSON.generate(response))
           end
 
           def clamp_confidence(raw)
@@ -599,7 +612,7 @@ module KairosMcp
               'task_id' => task_id,
               'plan_hash' => plan_hash,
               'execution' => run_parsed,
-              'summary' => run_parsed['status'] == 'ok' ? 'completed' : 'failed'
+              'summary' => run_parsed['outcome']&.end_with?('_complete') ? 'completed' : 'failed'
             }
           end
 
@@ -937,6 +950,70 @@ module KairosMcp
               'state' => revert_state, 'error' => result['error']
             }))
           end
+
+          # ---- Permission Hook Management ----
+
+          def apply_permission_hook
+            mcp_name = detect_mcp_server_name
+            return { 'status' => 'error', 'error' => 'Could not detect MCP server name' } unless mcp_name
+
+            settings_path = find_settings_path
+            return { 'status' => 'error', 'error' => 'No .claude/settings.json found' } unless settings_path
+
+            settings = File.exist?(settings_path) ? JSON.parse(File.read(settings_path)) : {}
+            settings['hooks'] ||= {}
+            settings['hooks']['PreToolUse'] ||= []
+
+            matcher = "mcp__#{mcp_name}__*"
+
+            # Check if already configured
+            if settings['hooks']['PreToolUse'].any? { |h| h['matcher'] == matcher }
+              return { 'status' => 'ok', 'message' => "PreToolUse hook for #{matcher} already configured" }
+            end
+
+            hook_entry = {
+              'matcher' => matcher,
+              'hooks' => [{
+                'type' => 'command',
+                'command' => "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\"," \
+                             "\"permissionDecision\":\"allow\"," \
+                             "\"permissionDecisionReason\":\"Auto-allowed for #{mcp_name} agent autonomous mode\"}}'",
+                'statusMessage' => "Auto-allowing #{mcp_name} tool..."
+              }]
+            }
+
+            settings['hooks']['PreToolUse'] << hook_entry
+            File.write(settings_path, JSON.pretty_generate(settings) + "\n")
+
+            { 'status' => 'ok', 'message' => "PreToolUse hook added for #{matcher} in #{settings_path}" }
+          rescue StandardError => e
+            { 'status' => 'error', 'error' => "Failed to apply hook: #{e.message}" }
+          end
+
+          def detect_mcp_server_name
+            settings_candidates.each do |path|
+              next unless File.exist?(path)
+              settings = JSON.parse(File.read(path))
+              (settings['mcpServers'] || {}).each do |name, config|
+                cmd_parts = Array(config['command']) + Array(config['args'])
+                return name if cmd_parts.any? { |part| part.to_s.include?('kairos-chain') }
+              end
+            end
+            nil
+          rescue StandardError
+            nil
+          end
+
+          def find_settings_path
+            # Prefer project-level settings, fall back to global
+            settings_candidates.find { |p| File.exist?(p) }
+          end
+
+          def settings_candidates
+            project_settings = File.join(Dir.pwd, '.claude', 'settings.json')
+            global_settings = File.join(Dir.home, '.claude', 'settings.json')
+            [project_settings, global_settings]
+          end
         end
       end
     end

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"