kairos-chain 3.6.2 → 3.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70e5ff9eff0a25ceba4e38cf6bdb7f0c7fb45bd1f11b9345148625fe86b48be2
-  data.tar.gz: 7de3d8c8b819cc86ab3847a60250ecc98fe1bf66077a10a9f43521910f51480b
+  metadata.gz: cef8ee3fd2052bb3d553e0c7ee0569d50f88fcfadea13dec6722122e2e71adb7
+  data.tar.gz: de6425c1fa691e86ad4e3597f36733b9ca592cb017ad58b69d54aecb64b63dd6
 SHA512:
-  metadata.gz: 4d8385510f0309d0705ac2a311da86f05c62332b77cf0f4cc7a0de7d271863f73e9137320d5d7470d5552c0b3da441500c178b7f3d5d8abd6e0b253ce7d562ed
-  data.tar.gz: f298792554a96d5da897523d9b6342d3fef2bc06e4d9a86d54a829c611fe5885fe6896168f7fc1853e3565bc2f4e71ed86d3740b39b898aaa4b0afc3c5337f4b
+  metadata.gz: bc9dec7fd29edf94dce3de1a18fc90eb006695cb22475195aeb4422f6aa843a0efc1b2fa2e5796891768934c7307fc0687d0420f2883a099b700a80077ae4b7a
+  data.tar.gz: db1e322c0b191ab12d949c403b6b04a5c6d99fccd9dd2e6528754a066a4bf3db26e4fb3e0cba4898826da13887d52f91c3018377a47aa5dd1ee25316f850f7df

data/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.7.0] - 2026-03-29
+
+### Added
+
+- **Dream SkillSet** — L2 memory consolidation and lifecycle management
+  - `dream_scan`: Pattern detection across L2 sessions — tag co-occurrence,
+    L2/L1 staleness (mtime-based), name overlap (Jaccard), archive candidate detection.
+    Filters soft-archived stubs from promotion candidates.
+  - `dream_archive`: L2 soft-archive — gzip compress .md, move full context directory
+    to archive, leave searchable stub (tags + summary). SHA256 verified inline.
+    Per-context flock. `dry_run: true` by default.
+  - `dream_recall`: Restore archived contexts with SHA256 integrity check.
+    Preview and verify-only modes (read-only, no permission required).
+  - `dream_propose`: Package L1 promotion proposals with ready-to-execute
+    `knowledge_update` commands. Optional Persona Assembly templates.
+  - L2 lifecycle model: Active → Candidate → Soft-Archived → Recalled
+  - `dream_trigger_policy` L1 knowledge for Kairotic trigger heuristics
+  - 119 tests across 27 test sections
+
+- **Agent SkillSet — permission advisory**
+  - `agent_start` now includes `permission_advisory` in response,
+    recommending users configure permission mode (Normal / Auto-allow / Auto-accept)
+    for smoother autonomous operation
+
+### Fixed
+
+- **L1 staleness detection** — use tag overlap and name token matching instead of
+  exact L1 name-in-L2-tags check. Reduces false positives from 48/48 to 7/48.
+
 ## [3.6.0] - 2026-03-28
 
 ### Added

data/lib/kairos_mcp/version.rb

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

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

@@ -95,13 +95,18 @@ module KairosMcp
             session.update_state('observed')
             session.save
 
-            text_content(JSON.generate({
+            result = {
               'status' => 'ok',
               'session_id' => session_id,
               'mandate_id' => mandate[:mandate_id],
               'state' => 'observed',
               'observation' => observation
-            }))
+            }
+
+            # Advisory: suggest permission mode for autonomous operation
+            result['permission_advisory'] = permission_advisory_message
+
+            text_content(JSON.generate(result))
           rescue ArgumentError => e
             text_content(JSON.generate({ 'status' => 'error', 'error' => e.message }))
           rescue StandardError => e
@@ -126,6 +131,22 @@ module KairosMcp
             )
           end
 
+          def permission_advisory_message
+            <<~MSG.strip
+              This agent session will execute tools autonomously.
+              For smoother operation, consider adjusting your permission mode:
+
+              1. Normal (default) — ask for each command. Safest, but interrupts flow.
+              2. Auto-allow — pre-approved commands only. Balanced.
+                 Configure in .claude/settings.local.json permissions.allow array.
+              3. Auto-accept — allow everything. Fastest for trusted tasks.
+                 Run /permissions and select auto mode, or start with --dangerously-skip-permissions.
+
+              Recommendation: For implementation + multi-LLM review workflows, auto-allow
+              with ruby/codex/agent commands pre-approved provides the best balance.
+            MSG
+          end
+
           def run_observe(goal_name)
             # Gather observation data without LLM
             observation = { 'goal_name' => goal_name, 'timestamp' => Time.now.iso8601 }

data/templates/skillsets/dream/config/dream.yml

@@ -0,0 +1,26 @@
+scan:
+  default_scope: "l2"
+  min_recurrence: 3
+  max_candidates: 5
+  skip_archived: true              # scan filters skip soft-archived stubs
+
+archive:
+  staleness_threshold_days: 90
+  dry_run_default: true            # safe by default
+  preserve_gzip: true
+  archive_dir: "dream/archive"
+
+bisociation:
+  enabled: false                   # off by default
+  min_pmi: 1.5
+  min_pair_count: 2
+  min_tag_types: 15
+  max_results: 5
+
+staleness:
+  method: "mtime"                  # explicit definition
+  # future options: "referenced" (requires reference tracking)
+
+recording:
+  scan_findings_only: true
+  archive_events: true

data/templates/skillsets/dream/knowledge/dream_trigger_policy/dream_trigger_policy.md

@@ -0,0 +1,96 @@
+---
+name: dream_trigger_policy
+version: "0.2.1"
+tags:
+  - dream
+  - trigger
+  - heuristics
+  - consolidation
+  - archival
+---
+
+# Dream Trigger Policy
+
+## Overview
+
+This knowledge defines the heuristics that determine when Dream SkillSet operations
+should be triggered. Dream is a memory consolidation system that scans L2 contexts
+for recurring patterns, manages soft-archival of stale contexts, and packages
+promotion proposals for L2-to-L1 elevation.
+
+## Trigger Heuristics
+
+### 1. Promotion Candidate Detection (Tag Co-occurrence)
+
+**Signal**: A tag appears in `min_recurrence` or more distinct sessions.
+
+- Default threshold: 3 sessions
+- Only live contexts are considered (soft-archived stubs are excluded)
+- Tags are extracted from YAML frontmatter of context `.md` files
+- Co-occurrence is counted per-session, not per-context (a tag appearing 5 times
+  in one session counts as 1 occurrence)
+
+**Action**: Include in `promotion_candidates` list for LLM evaluation.
+
+### 2. Consolidation Candidate Detection (Name Overlap)
+
+**Signal**: Two or more contexts share high name-token overlap (Jaccard similarity).
+
+- Default threshold: Jaccard >= 0.5
+- Comparison uses underscore-separated tokens from context names
+- Example: `deployment_notes` and `deployment_config_notes` share tokens
+  `deployment` and `notes`, yielding Jaccard = 2/3 = 0.67
+
+**Action**: Include in `consolidation_candidates` list for LLM evaluation.
+
+### 3. L2 Staleness Detection (Archive Candidates)
+
+**Signal**: A context's file modification time (mtime) exceeds the staleness threshold.
+
+- Default threshold: 90 days
+- Uses `File.mtime` on the context `.md` file
+- Only live contexts are candidates (already-archived stubs are excluded)
+- "Semantic reference" tracking is a future enhancement (v2.2+)
+
+**Action**: Include in `archive_candidates` list. Archive requires explicit
+`dry_run: false` to execute.
+
+### 4. L1 Staleness Detection
+
+**Signal**: An L1 knowledge skill's name does not appear in any recent L2 context tags.
+
+- Compares L1 knowledge names against the union of all L2 tags
+- L1 skills that are never referenced in L2 may indicate orphaned knowledge
+
+**Action**: Include in `health_summary.stale_l1` for informational purposes.
+No automatic action is taken on L1 knowledge.
+
+### 5. Bisociation Detection (Experimental)
+
+**Signal**: Two tags that rarely co-occur in the same session but each appear
+frequently across separate sessions.
+
+- Measured by Pointwise Mutual Information (PMI)
+- Off by default (`bisociation.enabled: false`)
+- Guarded by `min_pair_count >= 2` and `min_tag_types >= 15`
+- Brittle on small corpora; intended for mature knowledge bases
+
+**Action**: Advisory only. LLM evaluates substance; no auto-promotion.
+
+## When to Run dream_scan
+
+Recommended triggers:
+
+1. **Session boundary**: At the end of a work session, scan for new patterns
+2. **Periodic**: Weekly or bi-weekly for knowledge health monitoring
+3. **Before major work**: Scan to surface relevant prior knowledge
+4. **Autonomos integration**: As part of the autonomos reflect cycle
+
+## Interpretation Guidelines
+
+- Promotion candidates are suggestions, not mandates. The LLM should evaluate
+  whether the recurring pattern represents genuine reusable knowledge.
+- Archive candidates should be reviewed before archiving. The 90-day threshold
+  is a heuristic; some contexts may be intentionally long-lived.
+- Consolidation candidates may represent genuinely distinct concepts that happen
+  to share naming. Always verify semantic overlap before merging.

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

@@ -0,0 +1,417 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'yaml'
+require 'zlib'
+require 'time'
+
+module KairosMcp
+  module SkillSets
+    module Dream
+      class Archiver
+        LOCK_FILE = '.dream_lock'
+
+        def initialize(config: {})
+          archive_config = config.fetch('archive', {})
+          @archive_dir_name = archive_config.fetch('archive_dir', 'dream/archive')
+          @preserve_gzip = archive_config.fetch('preserve_gzip', true)
+        end
+
+        # Soft-archive a single L2 context.
+        # Moves full directory contents to archive, leaves stub-only dir.
+        #
+        # @param session_id [String] Session ID
+        # @param context_name [String] Context name
+        # @param summary [String] Caller-provided summary for the stub
+        # @return [Hash] Result with content_hash, sizes, moved_subdirs
+        def archive_context!(session_id:, context_name:, summary:)
+          src_dir  = context_dir_path(session_id, context_name)
+          arch_dir = archive_dir_path(session_id, context_name)
+          md_file  = File.join(src_dir, "#{context_name}.md")
+
+          with_lock(src_dir) do
+            # 1. Validate source exists and is not already archived
+            raise "Context not found: #{md_file}" unless File.exist?(md_file)
+            raise "Already archived: #{context_name}" if archived?(session_id: session_id, context_name: context_name)
+
+            # 2. Read and compress the markdown
+            original_content = File.read(md_file)
+            original_size = original_content.bytesize
+            content_hash = Digest::SHA256.hexdigest(original_content)
+
+            FileUtils.mkdir_p(arch_dir)
+            gz_path = File.join(arch_dir, "#{context_name}.md.gz")
+            Zlib::GzipWriter.open(gz_path) { |gz| gz.write(original_content) }
+
+            # 3. Verify gzip integrity immediately after write
+            verify_hash = Digest::SHA256.hexdigest(Zlib::GzipReader.open(gz_path, &:read))
+            unless verify_hash == content_hash
+              FileUtils.rm_f(gz_path)
+              raise "Gzip verification failed — archive aborted, original intact"
+            end
+
+            # 4. Move ALL subdirs/files (except .md and .dream_lock) to archive
+            moved_subdirs = []
+            Dir.children(src_dir).each do |child|
+              next if child == "#{context_name}.md"
+              next if child == LOCK_FILE
+
+              child_src = File.join(src_dir, child)
+              FileUtils.mv(child_src, File.join(arch_dir, child))
+              moved_subdirs << child if File.directory?(File.join(arch_dir, child))
+            end
+
+            # 5. Extract original frontmatter for stub metadata
+            original_meta = extract_frontmatter(original_content)
+
+            # 6. Detect what was moved for stub flags
+            has_scripts    = moved_subdirs.include?('scripts')
+            has_assets     = moved_subdirs.include?('assets')
+            has_references = moved_subdirs.include?('references')
+
+            # 7. Write stub atomically (tempfile + rename)
+            stub_content = generate_stub(
+              context_name: context_name,
+              summary: summary,
+              content_hash: content_hash,
+              original_size: original_size,
+              original_meta: original_meta,
+              archive_ref: archive_ref_path(session_id, context_name),
+              has_scripts: has_scripts,
+              has_assets: has_assets,
+              has_references: has_references
+            )
+            tmp_path = "#{md_file}.tmp"
+            File.write(tmp_path, stub_content)
+            File.rename(tmp_path, md_file) # POSIX atomic
+
+            {
+              success: true,
+              context_name: context_name,
+              session_id: session_id,
+              content_hash: content_hash,
+              original_size: original_size,
+              stub_size: stub_content.bytesize,
+              moved_subdirs: moved_subdirs,
+              verified: true
+            }
+          end
+        end
+
+        # Restore a soft-archived context.
+        #
+        # @param session_id [String] Session ID
+        # @param context_name [String] Context name
+        # @return [Hash] Result with restored_hash, verified
+        def recall_context!(session_id:, context_name:)
+          src_dir  = context_dir_path(session_id, context_name)
+          arch_dir = archive_dir_path(session_id, context_name)
+          md_file  = File.join(src_dir, "#{context_name}.md")
+          gz_path  = File.join(arch_dir, "#{context_name}.md.gz")
+
+          with_lock(src_dir) do
+            # 1. Verify archive exists and integrity
+            raise "Archive not found: #{gz_path}" unless File.exist?(gz_path)
+            raise "Stub not found: #{md_file}" unless File.exist?(md_file)
+
+            stub_meta = parse_stub(md_file)
+            restored_content = Zlib::GzipReader.open(gz_path, &:read)
+            restored_hash = Digest::SHA256.hexdigest(restored_content)
+
+            unless restored_hash == stub_meta[:content_hash]
+              raise "Archive integrity check failed. Expected #{stub_meta[:content_hash]}, " \
+                    "got #{restored_hash}. Archive may be corrupted."
+            end
+
+            # 2. Restore markdown atomically
+            tmp_path = "#{md_file}.tmp"
+            File.write(tmp_path, restored_content)
+            File.rename(tmp_path, md_file) # POSIX atomic
+
+            # 3. Move subdirectories and files back from archive
+            moved_back = []
+            Dir.children(arch_dir).each do |child|
+              next if child == "#{context_name}.md.gz"
+
+              child_arch = File.join(arch_dir, child)
+              FileUtils.mv(child_arch, File.join(src_dir, child))
+              moved_back << child
+            end
+
+            # 4. Clean up archive (configurable)
+            if @preserve_gzip
+              # Keep gzip for safety — no cleanup
+            else
+              FileUtils.rm_rf(arch_dir)
+            end
+
+            {
+              success: true,
+              context_name: context_name,
+              session_id: session_id,
+              restored_hash: restored_hash,
+              restored_size: restored_content.bytesize,
+              moved_back: moved_back,
+              verified: true,
+              archive_preserved: @preserve_gzip
+            }
+          end
+        end
+
+        # Preview archived content without restoring.
+        #
+        # @param session_id [String] Session ID
+        # @param context_name [String] Context name
+        # @return [Hash] Preview result with content and metadata
+        def preview(session_id:, context_name:)
+          arch_dir = archive_dir_path(session_id, context_name)
+          gz_path  = File.join(arch_dir, "#{context_name}.md.gz")
+          md_file  = File.join(context_dir_path(session_id, context_name), "#{context_name}.md")
+
+          raise "Archive not found: #{gz_path}" unless File.exist?(gz_path)
+
+          content = Zlib::GzipReader.open(gz_path, &:read)
+          stub_meta = File.exist?(md_file) ? parse_stub(md_file) : {}
+
+          {
+            success: true,
+            context_name: context_name,
+            session_id: session_id,
+            content: content,
+            content_size: content.bytesize,
+            content_hash: Digest::SHA256.hexdigest(content),
+            stub_meta: stub_meta
+          }
+        end
+
+        # Check if a context is soft-archived.
+        #
+        # @param session_id [String] Session ID
+        # @param context_name [String] Context name
+        # @return [Boolean]
+        def archived?(session_id:, context_name:)
+          md_file = File.join(context_dir_path(session_id, context_name), "#{context_name}.md")
+          return false unless File.exist?(md_file)
+
+          content = File.read(md_file)
+          status = extract_status(content)
+          status == 'soft-archived'
+        end
+
+        # Verify archive integrity without modifying anything.
+        #
+        # @param session_id [String] Session ID
+        # @param context_name [String] Context name
+        # @return [Hash] Verification result
+        def verify(session_id:, context_name:)
+          arch_dir = archive_dir_path(session_id, context_name)
+          md_file  = File.join(context_dir_path(session_id, context_name), "#{context_name}.md")
+          gz_path  = File.join(arch_dir, "#{context_name}.md.gz")
+
+          issues = []
+
+          # Check stub exists and is archived
+          unless File.exist?(md_file)
+            issues << "Stub file not found: #{md_file}"
+          end
+
+          stub_meta = {}
+          if issues.empty?
+            content = File.read(md_file)
+            status = extract_status(content)
+            unless status == 'soft-archived'
+              issues << "Context is not archived (status: #{status || 'nil'})"
+            end
+            stub_meta = parse_stub(md_file)
+          end
+
+          # Check gzip exists
+          unless File.exist?(gz_path)
+            issues << "Gzip archive not found: #{gz_path}"
+          end
+
+          # Verify SHA256 if both stub and gzip exist
+          if issues.empty? && stub_meta[:content_hash]
+            actual_hash = Digest::SHA256.hexdigest(Zlib::GzipReader.open(gz_path, &:read))
+            unless actual_hash == stub_meta[:content_hash]
+              issues << "SHA256 mismatch. Stub: #{stub_meta[:content_hash]}, Actual: #{actual_hash}"
+            end
+          end
+
+          # Check archived subdirs exist
+          if stub_meta[:archive_ref] && File.directory?(arch_dir)
+            archived_children = Dir.children(arch_dir).reject { |c| c.end_with?('.md.gz') }
+            has_expected = []
+            has_expected << 'scripts' if stub_meta[:has_scripts]
+            has_expected << 'assets' if stub_meta[:has_assets]
+            has_expected << 'references' if stub_meta[:has_references]
+
+            has_expected.each do |subdir|
+              unless archived_children.include?(subdir)
+                issues << "Expected archived subdir '#{subdir}' not found in archive"
+              end
+            end
+          end
+
+          {
+            success: issues.empty?,
+            context_name: context_name,
+            session_id: session_id,
+            issues: issues,
+            stub_meta: stub_meta,
+            gzip_exists: File.exist?(gz_path),
+            archive_dir_exists: File.directory?(arch_dir)
+          }
+        end
+
+        private
+
+        # ---------------------------------------------------------------
+        # Path helpers
+        # ---------------------------------------------------------------
+
+        def context_dir_path(session_id, context_name)
+          dir = context_dir
+          File.join(dir, session_id, context_name)
+        end
+
+        def archive_dir_path(session_id, context_name)
+          base = storage_dir
+          File.join(base, @archive_dir_name, session_id, context_name)
+        end
+
+        def archive_ref_path(session_id, context_name)
+          File.join(@archive_dir_name, session_id, context_name)
+        end
+
+        def context_dir
+          if defined?(KairosMcp) && KairosMcp.respond_to?(:context_dir)
+            KairosMcp.context_dir
+          else
+            File.join(Dir.pwd, '.kairos', 'context')
+          end
+        end
+
+        def storage_dir
+          if defined?(KairosMcp) && KairosMcp.respond_to?(:storage_dir)
+            KairosMcp.storage_dir
+          elsif defined?(KairosMcp) && KairosMcp.respond_to?(:kairos_dir)
+            KairosMcp.kairos_dir
+          else
+            File.join(Dir.pwd, '.kairos')
+          end
+        end
+
+        # ---------------------------------------------------------------
+        # Lock
+        # ---------------------------------------------------------------
+
+        def with_lock(dir)
+          FileUtils.mkdir_p(dir)
+          lock_path = File.join(dir, LOCK_FILE)
+          File.open(lock_path, File::CREAT | File::RDWR) do |f|
+            unless f.flock(File::LOCK_EX | File::LOCK_NB)
+              raise "Context is locked by another operation. Try again later."
+            end
+            begin
+              yield
+            ensure
+              f.flock(File::LOCK_UN)
+            end
+          end
+        ensure
+          FileUtils.rm_f(File.join(dir, LOCK_FILE)) if File.exist?(File.join(dir, LOCK_FILE))
+        end
+
+        # ---------------------------------------------------------------
+        # Stub generation and parsing
+        # ---------------------------------------------------------------
+
+        def generate_stub(context_name:, summary:, content_hash:, original_size:,
+                          original_meta:, archive_ref:, has_scripts:, has_assets:, has_references:)
+          title = original_meta['title'] || context_name
+          tags = Array(original_meta['tags'])
+          description = original_meta['description'] || ''
+
+          frontmatter = {
+            'title' => title,
+            'tags' => tags,
+            'description' => description,
+            'status' => 'soft-archived',
+            'archived_at' => Time.now.utc.iso8601,
+            'archived_by' => 'dream_archive',
+            'archive_ref' => archive_ref,
+            'content_hash' => content_hash,
+            'original_size' => original_size,
+            'has_scripts' => has_scripts,
+            'has_assets' => has_assets,
+            'has_references' => has_references,
+            'summary' => summary
+          }
+
+          includes = []
+          includes << 'scripts/' if has_scripts
+          includes << 'assets/' if has_assets
+          includes << 'references/' if has_references
+
+          body_lines = []
+          body_lines << "# #{context_name} [ARCHIVED]"
+          body_lines << ""
+          body_lines << "This context has been soft-archived. Use `dream_recall` to restore full text."
+          body_lines << ""
+          body_lines << "**Tags**: #{tags.join(', ')}" unless tags.empty?
+          body_lines << "**Original size**: #{format_bytes(original_size)}"
+          body_lines << "**Includes**: #{includes.join(', ')}" unless includes.empty?
+
+          "---\n#{YAML.dump(frontmatter).sub(/\A---\n/, '')}---\n\n#{body_lines.join("\n")}\n"
+        end
+
+        def parse_stub(md_file)
+          content = File.read(md_file)
+          meta = extract_frontmatter(content)
+          {
+            content_hash: meta['content_hash'],
+            original_size: meta['original_size'],
+            archive_ref: meta['archive_ref'],
+            archived_at: meta['archived_at'],
+            has_scripts: meta['has_scripts'] == true,
+            has_assets: meta['has_assets'] == true,
+            has_references: meta['has_references'] == true,
+            summary: meta['summary'],
+            status: meta['status']
+          }
+        end
+
+        # ---------------------------------------------------------------
+        # Frontmatter helpers
+        # ---------------------------------------------------------------
+
+        def extract_frontmatter(content)
+          if content =~ /\A---\n(.*?)\n---/m
+            YAML.safe_load($1, permitted_classes: [Symbol]) || {}
+          else
+            {}
+          end
+        rescue StandardError
+          {}
+        end
+
+        def extract_status(content)
+          meta = extract_frontmatter(content)
+          meta['status'] || meta[:status]
+        end
+
+        def format_bytes(bytes)
+          if bytes >= 1_048_576
+            "#{(bytes / 1_048_576.0).round(1)} MB"
+          elsif bytes >= 1024
+            "#{(bytes / 1024.0).round(1)} KB"
+          else
+            "#{bytes} bytes"
+          end
+        end
+      end
+    end
+  end
+end