kairos-chain 3.9.4 → 3.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa87c57bf88c7f0f225793d049592120e2872deccda39c3eba3a3af059663dac
-  data.tar.gz: bf793a2f05c4e41bc43aa1f1d5a948985eeac39cee0c9c4c1c744d577e0c32ef
+  metadata.gz: 0acca30b533051c884363e6c9215394d308f501985a6dc647f92c513e875ce6b
+  data.tar.gz: 862c366ebcb1f88a66eb5c30b48086e454145609d57f1fbb8ba6aa62aeb89652
 SHA512:
-  metadata.gz: 27ea12fe7352161972a0e81754a8012ba03da6e03c4f1db6fd4f51bb60d599f0ebc1777c54a8d8169b138e308b035628666d80dcccdf95ad1b82f78fb047295c
-  data.tar.gz: 811bd5bf6f2339086196f1ea8edfe22371b3374bb1290ebbece3f8696c3a7c514baafbd24a1bf4cc7f7df0f8e29f0c825f1b36f2b22122345d3fcf704dab8141
+  metadata.gz: 9066154fcf88d0e39457fca4c4f4ebac74e7104c9d5d2bf047783e2f058ddfc9b03e38be965f492ac914b81eb611da50cff7e63264e6a16caadf0e23d8d707ef
+  data.tar.gz: b7324da5f140698a74d11e94dedee3a3bdc2d778a9f0f2ca12417861bb5a5b23ad96eb6f4ad94077c1b6f72cbc2f2e0c3651c62d08242452451d7f0ada75d330

data/CHANGELOG.md

@@ -4,6 +4,58 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.11.0] - 2026-04-01
+
+### Added
+
+- **`llm_call` `output_schema` parameter** — Enables structured JSON output from LLMs.
+  When provided, the LLM is constrained to return JSON matching the given JSON Schema.
+  - Anthropic/Bedrock: system prompt injection with tools-aware qualifier
+    ("When you are NOT using a tool, respond with ONLY valid JSON...")
+  - OpenAI: native `response_format: { type: "json_schema", strict: true }`
+  - Claude Code CLI: prompt text injection
+  - Backward compatible: `nil` default preserves all existing behavior
+- **`SchemaConverter.normalize_for_openai` `required` auto-population** — When an
+  object schema has no `required` key, all property names are auto-populated into
+  `required` to satisfy OpenAI strict mode constraints. Existing `required` arrays
+  are preserved unchanged.
+- **Multi-LLM review XML block prompts** (`multi_llm_review_workflow` v3.2) — Five
+  XML blocks for structured review prompts:
+  `<task>`, `<structured_output_contract>`, `<grounding_rules>`,
+  `<verification_loop>`, `<default_follow_through_policy>`.
+  LLM-agnostic; works with Claude, GPT, and Composer models.
+
+### Design Process
+
+- Inspired by codex-plugin-cc (Claude Code Codex plugin) analysis — 4-agent team review
+- Implementation reviewed: 2 rounds x 3 LLMs (Claude Opus 4.6, Codex GPT-5.4, Cursor Composer-2)
+- R1: 3/3 APPROVE WITH CHANGES — 2 must-fix findings (tools+schema conflict, OpenAI required)
+- R2: 2/3 APPROVE, 1/3 AWC, 0 FAIL/HIGH — converged
+- Tests: 32 → 47 (all PASS)
+
+## [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

@@ -5,6 +5,7 @@ require 'fileutils'
 require_relative 'base_tool'
 require_relative '../upgrade_analyzer'
 require_relative '../config_merger'
+require_relative '../skillset_manager'
 
 module KairosMcp
   module Tools
@@ -240,6 +241,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 +444,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.11.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/knowledge/multi_llm_review_workflow/multi_llm_review_workflow.md

@@ -1,7 +1,7 @@
 ---
 name: multi_llm_review_workflow
 description: "Multi-LLM review methodology and execution — workflow pattern, CLI tooling, consensus analysis, Persona Assembly. Applicable to design, implementation, documentation, or any artifact."
-version: "3.1"
+version: "3.2"
 tags:
   - workflow
   - review
@@ -243,6 +243,65 @@ Every review prompt MUST include these 7 items:
 
 All prompt content MUST be in **English** for consistent parsing across LLM tools.
 
+### XML Block Structure for Review Prompts
+
+Review prompts SHOULD use XML blocks to give LLMs explicit structural contracts.
+This reduces hallucination, enforces grounded findings, and standardizes output.
+
+```xml
+<task>
+Review the provided artifact for [review type: design correctness / implementation bugs / ...].
+Target: [artifact name and version]
+Scope: [what changed since last round, or "initial review"]
+</task>
+
+<structured_output_contract>
+Output a Markdown file with this structure:
+- **Reviewer**: [tool_name]
+- **Model**: [model_id]
+- **Date**: [ISO date]
+- **Overall Verdict**: APPROVE / APPROVE WITH CHANGES / REJECT
+
+For each finding:
+- **Severity**: FAIL / HIGH / MEDIUM / LOW
+- **Confidence**: 0.0-1.0 (how certain you are this is a real issue)
+- **Location**: file:line or section reference
+- **What can go wrong**: concrete failure scenario
+- **Why this is vulnerable**: code path or design gap
+- **Likely impact**: data loss, security breach, silent corruption, etc.
+- **Recommended fix**: specific change (not "consider improving")
+</structured_output_contract>
+
+<grounding_rules>
+Ground every finding in the provided artifact text or referenced source files.
+If a claim is an inference (not directly visible in the artifact), label it:
+  "[INFERRED] Based on X, this likely means Y."
+Do not invent files, methods, or runtime behavior not shown in the artifact.
+Keep confidence scores honest — 0.5 if uncertain, 0.9+ only if directly evidenced.
+</grounding_rules>
+
+<verification_loop>
+Before finalizing your review:
+1. Re-read each FAIL/HIGH finding. Is the failure scenario concrete and reproducible?
+2. Check for second-order failures: empty-state, retry, stale state, rollback risk.
+3. Verify file paths and line numbers are accurate.
+4. If you found zero issues, state that explicitly — do not manufacture findings.
+</verification_loop>
+
+<default_follow_through_policy>
+Complete the full review in one pass. Do not ask clarifying questions.
+If context is missing, note it as a finding with severity LOW and confidence 0.3.
+</default_follow_through_policy>
+```
+
+**Usage**: Include these XML blocks in the prompt body (rule #3 "Review instructions").
+They replace or supplement free-form review instructions. The blocks are
+LLM-agnostic and work with Claude, GPT, and Composer models.
+
+**When to use full XML blocks vs. lightweight**:
+- **Full** (all 5 blocks): Design review, implementation review, security-critical
+- **Lightweight** (`<task>` + `<structured_output_contract>` only): Fix plan review, document review
+
 ### Output Directive in Prompt Body
 
 The prompt body itself (what the LLM sees) must contain:

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