kairos-chain 3.29.6 → 3.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fde5a098059d86d9dc9f10cbf27911ff0f6e3defede0c118ac36825964e4d55
-  data.tar.gz: a5b4283909071dba96fa4919a59ef29881f084f76a8fd8cc3335fcbb9efdb8d9
+  metadata.gz: 3ec94fadb095a49a89c0235010c80e37913aaf6781aa16d22a2e5855b1eb154d
+  data.tar.gz: 38c3b631326b87f07285f9a5f4ecdd64fc22d086b6b08de76d5b2aaf2d7d7040
 SHA512:
-  metadata.gz: a863d1090ee8f1bffaf6a47848d01f113983d2b2efefd7d7e1e6ecec89105fbdde85851681f163be8d93d79734d6bfaf23dfa0080436ec9a15e0e2e258db2d52
-  data.tar.gz: 93690b91d30df69e0dc634b135dc3492a436089e6af02906ed4cfaf22e8fb42f5e174fa500dfb1fc906096b3b6fbb275cf043399042a642f9847a28a471147b8
+  metadata.gz: 7d3d7e9d5f52b58109a795ce4f67243551ad353d18d273d4062034e09bcafe8201559ceabcef16c5ad0d0fc0bca4b8b8629c27cb49e224091ae05ffd5aa364ac
+  data.tar.gz: a20e8e7a2cb18d8cbcbd76f39c7fa69a9bbd55d4447c16fa289ca8227fd2537325693748e711e46e57693c6572b41f15096dc358368f89911d95eaea3c714ca8

data/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.30.0] - 2026-06-08
+
+### Added — `dream_digest`: derived narrative view over L2/L1 fragments (dream SkillSet v0.3.0)
+
+A new `dream_digest` tool in the `dream` SkillSet, providing `narrative_digest`.
+Inspired by OpenAI ChatGPT "Dreaming" memory, but inverted to KairosChain
+principles: synthesis is adopted while the synthesized result is demoted from a
+source of truth to a regenerable DERIVED view that sits beside the immutable
+fragments — never an overwrite, never authoritative (Prop 5 + Knowledge Ethos).
+
+- Modes: `package` (content-addressed snapshot + contradiction-preserving
+  directive), `write` (persist LLM content with provenance), `read` (with
+  staleness annotations), `list`, `sweep` (staleness + age health, schedulable),
+  `refresh` (faithful regeneration package from recorded provenance).
+- `from_tag` wiring: resolves the citable universe (the snapshot input) from a
+  tag, connecting `dream_scan` detection to digest generation.
+- Design frozen after 3 multi-LLM design rounds (10 invariants); implementation
+  hardened across 3 implementation-review rounds (path-traversal confinement,
+  slug-collision guard, per-topic write lock, provenance re-derivation at write,
+  symlink-resolving confinement, fail-closed access bound).
+- Tests: `test_dream_digest.rb` (74), `test_dream_digest_live.rb` (11 wiring).
+
+### Changed — `multi_llm_reviewer_evaluation` v1.5
+
+- Added "Review-Loop Operation Observations": (1) a SKIPped strict reviewer is a
+  coverage hole, not a pass; (2) treadmill vs healthy narrowing via per-round
+  (a)/(b)/(c) classification + a pre-committed freeze criterion.
+
 ## [3.29.6] - 2026-06-05
 
 ### Changed — `skill_authoring_patterns` readability + structure (v1.4)

data/lib/kairos_mcp/version.rb

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

data/templates/knowledge/multi_llm_reviewer_evaluation/multi_llm_reviewer_evaluation.md

@@ -1,7 +1,7 @@
 ---
 name: multi_llm_reviewer_evaluation
 description: "Multi-LLM reviewer performance evaluation — strengths, weaknesses, value-system biases, and recommended workflows. Based on 185+ reviews (Phase 1, 2026-02 to 03) + Phase 2 Case A 4-round Codex bias study (2026-05-04)."
-version: "1.4"
+version: "1.5"
 tags:
   - multi-llm
   - review
@@ -294,6 +294,36 @@ Deployment:         Composer-2.5 or Cursor GPT-5.4
    classification (see § Reviewer Value-System Divergence) is required to separate
    blocking signal from advisory noise. Codex models in particular require this lens.
 
+## Review-Loop Operation Observations (2026-06-06, dream_digest design loop)
+
+Two operational lessons from a 3-round design-by-invariant review loop (dream_digest,
+orchestrator Opus 4.8, full roster). These concern HOW to run the loop, complementing the
+per-reviewer profiles above.
+
+### 1. A SKIPped strict reviewer is a coverage hole, not a pass
+
+When a strict reviewer fails to run (e.g. Codex `token_invalidated` 401 -> SKIP), the
+remaining roster can hit the APPROVE threshold and report FALSE convergence. In the dream_digest
+loop, the first R1 showed 3/5 APPROVE only because both Codex SKIPped on auth failure; after
+`codex login` re-auth, the same artifact immediately went to REVISE, and Codex GPT-5.4 SOLO
+caught an access-control aggregation leak (a genuine (a)) that no other reviewer saw. Rule:
+do not treat threshold-APPROVE as convergence while the strongest (a)-finder (Codex) is absent.
+Re-auth and re-run before trusting a verdict. Surface SKIPs prominently in the per-reviewer table.
+
+### 2. Treadmill vs healthy narrowing — distinguish by per-round (a)/(b)/(c), then pre-commit a freeze criterion
+
+Codex may never reach APPROVE (value-system divergence). This looks like the non-convergent
+treadmill (Context Graph: 24/24 REJECT, new P0 each round) but is NOT the same if findings
+NARROW monotonically. In the dream_digest loop they did: R1 structural gaps -> R2 fix-incompleteness
+-> R3 a single (b) one-liner (an I7xI9 recording inconsistency), all else (c). To tell the two
+apart you MUST classify every finding (a)/(b)/(c) each round and watch the trend.
+
+To stop the treadmill structurally, PRE-COMMIT a freeze criterion before the round, e.g.:
+"revise only on a new (a) or an internal-contradiction (b); a request to specify the ENFORCEMENT
+MECHANISM of a sound invariant is (c) -> §11 / implementation review." This converts "wait for
+Codex APPROVE" (not always reachable) into "freeze when only (c)/mechanism findings remain,"
+which is decidable by the orchestrator and resistant to value-divergence stalling.
+
 ## Refinement Source
 
 Profiles in this knowledge are refined from accumulated L2 contexts named with prefix

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

@@ -0,0 +1,589 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'yaml'
+require 'json'
+require 'time'
+require 'date'
+
+module KairosMcp
+  module SkillSets
+    module Dream
+      # Digester — generates and reads dream_digest derived views.
+      #
+      # Implements the frozen design (dream_digest_design_v0.4):
+      #   - I1/I8/I10: digests live in a NON-CANONICAL derived tier, per-topic, never authoritative.
+      #   - I2/I7: generation captures a content-addressed snapshot of the entire READ set.
+      #   - I4: provenance references the snapshot; an empty topic emits no digest.
+      #   - I5: post-generation source drift is labelled (stale), never corrected.
+      #   - I6: the snapshot fixes the citable universe as INPUT (the LLM phrases, it does not select).
+      #   - I9: the access bound is the most restrictive among ALL read sources (bound computed
+      #         and recorded here; full enforcement mechanism is deferred to §11 / implementation review).
+      #
+      # Synthesis CONTENT is generated outside this class (by an LLM), mirroring dream_propose:
+      #   #package builds the snapshot + a contradiction-preserving directive;
+      #   #write persists LLM-provided content with provenance;
+      #   #read returns content with staleness annotations.
+      class Digester
+        DIGEST_DIR_NAME = 'dream/digest'
+        LOCK_FILE = '.dream_digest_lock'
+
+        class IdentifierError < StandardError; end
+
+        def initialize(config: {})
+          @config = config || {}
+        end
+
+        # Build a content-addressed snapshot + generation directive for a topic. (I2/I6/I7)
+        #
+        # The citable universe (I6) is fixed here, as an INPUT, either explicitly via `sources`
+        # or — wiring dream_scan detection into the digest — by resolving every live fragment
+        # carrying `from_tag`. Explicit sources take precedence; from_tag is the auto path.
+        #
+        # @param topic [String]
+        # @param sources [Array<Hash>] each: {"layer"=>"l2"|"l1", "session_id"=>.., "name"=>..}
+        # @param from_tag [String, nil] resolve sources = all live fragments carrying this tag
+        # @param include_l1 [Boolean] when resolving from_tag, also include L1 entries tagged with it
+        # @param directive_id [String, nil]
+        # @return [Hash] { topic:, snapshot: [...], access_bound:, directive:, directive_id:, status:, resolved_from: }
+        def package(topic:, sources: nil, from_tag: nil, include_l1: true, directive_id: nil)
+          resolved_from = nil
+          src = Array(sources)
+          if src.empty? && from_tag
+            src = resolve_sources_by_tag(from_tag, include_l1: include_l1)
+            resolved_from = "tag:#{from_tag}"
+          end
+
+          read_set = build_read_set(src)
+          {
+            topic: topic,
+            directive_id: directive_id || default_directive_id,
+            snapshot: read_set,
+            access_bound: access_bound(read_set),
+            directive: generation_directive(topic, read_set),
+            resolved_from: resolved_from,
+            status: read_set.empty? ? 'no_sources' : 'needs_content'
+          }
+        end
+
+        # Resolve the citation set from a tag (dream_scan -> dream_digest wiring). (I6 input)
+        # Returns live (non-archived) L2 contexts carrying the tag, plus tagged L1 entries.
+        #
+        # @param tag [String]
+        # @param include_l1 [Boolean]
+        # @return [Array<Hash>] source descriptors for #build_read_set
+        def resolve_sources_by_tag(tag, include_l1: true)
+          out = []
+          cm = context_manager
+          if cm
+            cm.list_sessions.each do |session|
+              sid = session[:session_id]
+              cm.list_contexts_in_session(sid).each do |ctx|
+                # Route through l2_path so the same safe_seg?/confine guard applies here as in
+                # build_read_set (defense in depth even though listings come from the store).
+                path = l2_path(sid, ctx[:name])
+                next unless path && File.exist?(path)
+
+                content = safe_read(path)
+                next if content.nil?
+                next if frontmatter_value(content, 'status') == 'soft-archived' # don't cite stubs as live
+                next unless tag_match?(frontmatter_tags(content), tag)
+
+                out << { 'layer' => 'l2', 'session_id' => sid, 'name' => ctx[:name] }
+              end
+            end
+          end
+
+          if include_l1 && (kp = knowledge_provider)
+            kp.list.each do |entry|
+              next unless tag_match?(Array(entry[:tags]), tag)
+
+              out << { 'layer' => 'l1', 'name' => entry[:name] }
+            end
+          end
+          out
+        end
+
+        # Persist an LLM-generated digest with provenance. (I1/I4/I8/I10)
+        #
+        # @param topic [String]
+        # @param snapshot [Array<Hash>] the READ set from #package (citable universe, I6)
+        # @param content [String] LLM-generated narrative (cites only snapshot sources)
+        # @param directive_id [String]
+        # @return [Hash] { success:, topic:, output_hash:, provenance_count:, access_bound:, path: }
+        def write(topic:, snapshot:, content:, directive_id: nil, resolved_from: nil)
+          slug = slugify(topic)
+          raise 'empty topic slug' if slug.empty?
+          raise 'no provenance: refusing to emit a sourceless digest (I4)' if Array(snapshot).empty?
+          raise 'empty content' if content.nil? || content.strip.empty?
+
+          effective_directive = directive_id || default_directive_id
+          output_hash = Digest::SHA256.hexdigest(content)
+          dir = topic_dir(topic)
+          FileUtils.mkdir_p(dir)
+          path = File.join(dir, "#{slug}.md")
+          result = nil
+
+          # Hold the per-topic lock across BOTH snapshot capture and commit, so the recorded
+          # provenance hashes reflect source state at (or very near) commit time and concurrent
+          # same-topic writers cannot interleave (I3-style integrity).
+          with_topic_lock(dir) do
+            # Re-derive from CURRENT sources; never trust caller hashes/access (I4/I9). The
+            # caller's snapshot only fixes WHICH sources are citable (I6).
+            read_set = build_read_set(sources_from_provenance(snapshot))
+            raise 'no resolvable sources at write time (I4)' if read_set.empty?
+
+            bound = access_bound(read_set)
+            generated_at = Time.now.utc.iso8601
+            provenance = read_set.map { |s| s.slice('layer', 'ref', 'content_hash') }
+
+            frontmatter = {
+              'topic' => topic, 'kind' => 'dream_digest', 'status' => 'fresh',
+              'derived' => true, 'authoritative' => false, 'generated_at' => generated_at,
+              'directive_id' => effective_directive, 'access_bound' => bound,
+              'output_hash' => output_hash, 'provenance' => provenance
+            }
+            frontmatter['resolved_from'] = resolved_from if resolved_from
+            body = "---\n#{YAML.dump(frontmatter).sub(/\A---\n/, '')}---\n\n#{content.strip}\n"
+
+            guard_slug_collision!(path, topic) # I10: never silently overwrite a different topic
+            tmp = "#{path}.#{Process.pid}.#{rand(1 << 32).to_s(16)}.tmp" # unique per writer (I3)
+            begin
+              File.write(tmp, body)
+              File.rename(tmp, path) # POSIX atomic
+            ensure
+              File.delete(tmp) if File.exist?(tmp) # no orphan tmp on failure
+            end
+
+            result = {
+              success: true, topic: topic, path: path, output_hash: output_hash,
+              directive_id: effective_directive, provenance: provenance,
+              provenance_count: read_set.size, access_bound: bound, generated_at: generated_at
+            }
+          end
+          result
+        end
+
+        # Read a digest with staleness annotations. (I5)
+        #
+        # @return [Hash] { found:, topic:, content:, stale:, drifted:, access_bound:, age_days:, ... }
+        def read(topic:)
+          path = File.join(topic_dir(topic), "#{slugify(topic)}.md")
+          return { found: false, topic: topic } unless File.exist?(path)
+
+          raw = File.read(path)
+          meta = extract_frontmatter(raw)
+          body = raw.sub(/\A---\n.*?\n---\n/m, '').strip
+
+          drift = drifted_sources(meta['provenance'] || [])
+          {
+            found: true,
+            topic: topic,
+            path: path,
+            content: body,
+            access_bound: meta['access_bound'],
+            generated_at: meta['generated_at'],
+            age_days: age_days(meta['generated_at']),
+            directive_id: meta['directive_id'],
+            resolved_from: meta['resolved_from'],
+            provenance_count: Array(meta['provenance']).size,
+            drifted: drift,
+            stale: !drift.empty?
+          }
+        end
+
+        # Sweep all digests for staleness + age. Schedulable health view. (I5 + freshness)
+        # The EXTERNAL trigger (cron / Claude Code hook / autonomous loop) is a separate layer;
+        # this method only reports — it does not regenerate or schedule anything itself.
+        #
+        # @param stale_after_days [Integer, nil] also flag digests older than this as 'aged'
+        # @return [Array<Hash>] one entry per digest, sorted stale-first then oldest-first
+        def sweep(stale_after_days: nil)
+          list.map do |slug|
+            r = read(topic: slug)
+            next nil unless r[:found]
+
+            aged = stale_after_days && r[:age_days] && r[:age_days] >= stale_after_days
+            {
+              topic: slug,
+              stale: r[:stale],
+              drifted_count: Array(r[:drifted]).size,
+              age_days: r[:age_days],
+              aged: !!aged,
+              needs_refresh: r[:stale] || !!aged,
+              access_bound: r[:access_bound],
+              generated_at: r[:generated_at]
+            }
+          end.compact.sort_by { |e| [e[:needs_refresh] ? 0 : 1, -(e[:age_days] || 0)] }
+        end
+
+        # Produce a FRESH regeneration package for an existing digest, faithfully from its
+        # recorded provenance re-read at current content (I6: same citable universe, new content).
+        # Returns a package-shaped hash for the LLM to regenerate, then #write. Re-synthesis of a
+        # DERIVED view — never an overwrite of sources (I1/I5).
+        #
+        # @param topic [String]
+        # @return [Hash] package-shaped { topic:, snapshot:, directive:, dropped:, status:, ... }
+        def refresh(topic:)
+          existing = read(topic: topic)
+          return { found: false, topic: topic } unless existing[:found]
+
+          path = File.join(topic_dir(topic), "#{slugify(topic)}.md")
+          prior_prov = Array(extract_frontmatter(File.read(path))['provenance'])
+          sources = sources_from_provenance(prior_prov)
+
+          read_set = build_read_set(sources)
+          resolved_refs = read_set.map { |s| s['ref'] }
+          dropped = prior_prov.map { |p| stringify(p)['ref'] } - resolved_refs
+
+          {
+            found: true,
+            topic: topic,
+            directive_id: existing[:directive_id] || default_directive_id,
+            snapshot: read_set,
+            access_bound: access_bound(read_set),
+            directive: generation_directive(topic, read_set),
+            dropped: dropped, # sources no longer resolvable, omitted per I4
+            resolved_from: existing[:resolved_from], # carry origin forward across refresh
+            prior_age_days: existing[:age_days],
+            status: read_set.empty? ? 'no_sources' : 'needs_content'
+          }
+        end
+
+        # Staleness check without returning full content. (I5)
+        def staleness(topic:)
+          r = read(topic: topic)
+          return { found: false, topic: topic } unless r[:found]
+
+          { found: true, topic: topic, stale: r[:stale], drifted: r[:drifted],
+            provenance_count: r[:provenance_count] }
+        end
+
+        # List existing digests.
+        def list
+          base = digest_base
+          return [] unless Dir.exist?(base)
+
+          Dir.children(base).select { |c| Dir.exist?(File.join(base, c)) }.sort
+        end
+
+        private
+
+        # ---- READ set / snapshot --------------------------------------------------
+
+        def build_read_set(sources)
+          seen = {}
+          Array(sources).each_with_object([]) do |s, acc|
+            layer = (s['layer'] || s[:layer] || 'l2').to_s.downcase
+            path = source_path(layer, s)
+            next unless path && File.exist?(path)
+
+            content = safe_read(path)
+            next if content.nil? # unreadable -> treat as unresolvable (I4 drop), do not raise
+
+            ref = source_ref(layer, s)
+            key = "#{layer}|#{ref}"
+            next if seen[key] # dedup: a source cited twice contributes one provenance entry
+
+            seen[key] = true
+            acc << {
+              'layer' => layer,
+              'ref' => ref,
+              'path' => path,
+              'content_hash' => Digest::SHA256.hexdigest(content),
+              'access' => extract_access(content)
+            }
+          end
+        end
+
+        # Reconstruct source descriptors from recorded provenance / a package snapshot (for
+        # #refresh and #write). Reads only layer + ref, so caller-supplied hashes are never trusted.
+        def sources_from_provenance(provenance)
+          Array(provenance).filter_map do |p|
+            h = stringify(p)
+            case h['layer']
+            when 'l2'
+              sid, name = h['ref'].to_s.split('/', 2)
+              next nil unless sid && name
+
+              { 'layer' => 'l2', 'session_id' => sid, 'name' => name }
+            when 'l1'
+              { 'layer' => 'l1', 'name' => h['ref'] }
+            end
+          end
+        end
+
+        # Whole days since an ISO8601 timestamp (nil if unparseable). Time.now is fine in the gem.
+        def age_days(iso)
+          return nil if iso.nil? || iso.to_s.empty?
+
+          ((Time.now - Time.parse(iso.to_s)) / 86_400).floor
+        rescue StandardError
+          nil
+        end
+
+        def drifted_sources(provenance)
+          Array(provenance).filter_map do |p|
+            h = stringify(p)
+            path = path_for_ref(h['layer'], h['ref'])
+            content = (path && File.exist?(path)) ? safe_read(path) : nil
+            current = content && Digest::SHA256.hexdigest(content)
+            # A missing/unreadable source, or a hash mismatch, is drift (I5).
+            if current.nil? || current != h['content_hash']
+              reason = path.nil? || content.nil? ? 'missing' : 'hash_changed'
+              { 'ref' => h['ref'], 'reason' => reason }
+            end
+          end
+        end
+
+        # Read a file, returning nil on any I/O error instead of raising (callers treat nil as
+        # unresolvable / missing — keeps package/read/refresh from throwing out of the Digester).
+        def safe_read(path)
+          File.read(path)
+        rescue StandardError
+          nil
+        end
+
+        # ---- Access bound (I9) ----------------------------------------------------
+
+        # Most restrictive access label among the READ set. v0.1 reads a `visibility`/`access`
+        # frontmatter key if present; absent it, defaults to 'default'. Full ACL enforcement
+        # (live re-evaluation, principal binding) is a §11 / implementation-review mechanism.
+        ACCESS_ORDER = { 'private' => 3, 'restricted' => 2, 'default' => 1, 'public' => 0 }.freeze
+
+        def access_bound(read_set)
+          labels = Array(read_set).map { |s| (s['access'] || s[:access] || 'default').to_s }
+          labels << 'default' if labels.empty?
+          # Unknown labels are treated as MOST restrictive (fail-closed), never downgraded.
+          max_known = ACCESS_ORDER.values.max
+          winner = labels.max_by { |l| ACCESS_ORDER.fetch(l, max_known) }
+          # Normalize an unknown winning label to a known most-restrictive level so the stored
+          # bound is always a recognized value downstream consumers can compare.
+          ACCESS_ORDER.key?(winner) ? winner : 'private'
+        end
+
+        def extract_access(content)
+          meta = extract_frontmatter(content)
+          (meta['visibility'] || meta['access'] || 'default').to_s
+        end
+
+        # ---- Generation directive (I3/I6) -----------------------------------------
+
+        def generation_directive(topic, read_set)
+          refs = read_set.map { |s| s['ref'] }.join(', ')
+          <<~DIRECTIVE
+            Synthesize a narrative DIGEST for topic "#{topic}" from the source set below.
+
+            HARD CONSTRAINTS (do not violate):
+            - Cite ONLY these sources; do not introduce facts not grounded in them (I6 citable universe): #{refs}
+            - Every assertion must be traceable to at least one source; drop anything you cannot ground (I4).
+            - When sources DISAGREE, do NOT pick a winner and do NOT merge into one claim.
+              Surface the disagreement as coexisting positions with an inline annotation
+              (e.g. "Source A holds X; Source B holds Y; unresolved.") (I3, flat-annotation grade).
+            - This is a DERIVED overview, never authoritative; it must read as a projection of the
+              fragments, not as a new source of truth (I1).
+
+            Output: prose only (no YAML frontmatter — the tool adds provenance).
+          DIRECTIVE
+        end
+
+        def default_directive_id
+          'dream_digest.synthesis.v1'
+        end
+
+        # ---- Paths ----------------------------------------------------------------
+
+        def digest_base
+          File.join(kairos_dir, DIGEST_DIR_NAME)
+        end
+
+        def topic_dir(topic)
+          File.join(digest_base, slugify(topic))
+        end
+
+        # Serialize same-topic writes (I3-style integrity): concurrent generations of the same
+        # topic must not clobber each other. Unlike a global lock, this is per-topic-dir.
+        def with_topic_lock(dir)
+          FileUtils.mkdir_p(dir)
+          lock_path = File.join(dir, LOCK_FILE)
+          File.open(lock_path, File::CREAT | File::RDWR) do |f|
+            f.flock(File::LOCK_EX)
+            begin
+              yield
+            ensure
+              f.flock(File::LOCK_UN)
+            end
+          end
+        end
+
+        # I10: a digest file is per-topic. Same topic overwriting itself is regeneration (allowed);
+        # a DIFFERENT topic mapping to the same slug must fail loudly, never silently overwrite.
+        def guard_slug_collision!(path, topic)
+          return unless File.exist?(path)
+
+          existing = extract_frontmatter(safe_read(path).to_s)['topic']
+          return if existing == topic # same topic -> regeneration is allowed
+
+          # Different topic, OR an existing file whose topic cannot be determined (corrupt/
+          # unreadable): refuse to overwrite. Fail-closed so I10 holds even on damaged state.
+          detail = existing.nil? ? 'an existing file with no identifiable topic (corrupt?)' : "existing #{existing.inspect}"
+          raise IdentifierError,
+                "slug collision: topic #{topic.inspect} would overwrite #{detail} " \
+                "at #{File.basename(path)}; rename the topic or remove the file."
+        end
+
+        def source_path(layer, s)
+          case layer
+          when 'l2'
+            l2_path(s['session_id'] || s[:session_id], s['name'] || s[:name])
+          when 'l1'
+            l1_path(s['name'] || s[:name])
+          end
+        end
+
+        def path_for_ref(layer, ref)
+          case layer
+          when 'l2'
+            # name cannot contain '/' (safe_seg?), so split is unambiguous.
+            sid, name = ref.to_s.split('/', 2)
+            l2_path(sid, name)
+          when 'l1'
+            l1_path(ref)
+          end
+        end
+
+        def l2_path(sid, name)
+          return nil unless safe_seg?(sid) && safe_seg?(name)
+
+          confine(context_dir, File.join(context_dir, sid, name, "#{name}.md"))
+        end
+
+        def l1_path(name)
+          return nil unless safe_seg?(name)
+
+          # Pick the existing form FIRST, then confine the chosen path. (confine resolves symlinks
+          # via realpath, which only works on existing paths; confining a nonexistent form would
+          # mismatch a symlinked base such as macOS /var -> /private/var.)
+          dir_form  = File.join(knowledge_dir, name, "#{name}.md")
+          flat_form = File.join(knowledge_dir, "#{name}.md")
+          chosen = File.exist?(dir_form) ? dir_form : (File.exist?(flat_form) ? flat_form : nil)
+          chosen && confine(knowledge_dir, chosen)
+        end
+
+        # Reject identifiers that could escape the data tree or break the "sid/name" ref split.
+        def safe_seg?(value)
+          s = value.to_s
+          return false if s.empty?
+          return false if s.include?('/') || s.include?('\\') || s.include?("\0")
+          return false if ['.', '..'].include?(s)
+
+          true
+        end
+
+        # Return path only if it stays within base; else nil (defense in depth). Uses realpath
+        # when the target exists so a symlink under the data tree cannot escape it; falls back to
+        # lexical expand_path for not-yet-existing paths (which cannot follow a link until created).
+        def confine(base, path)
+          b = real_or_expand(base)
+          p = real_or_expand(path)
+          (p == b || p.start_with?("#{b}#{File::SEPARATOR}")) ? path : nil
+        end
+
+        def real_or_expand(x)
+          File.realpath(x)
+        rescue StandardError
+          File.expand_path(x)
+        end
+
+        def source_ref(layer, s)
+          case layer
+          when 'l2' then "#{s['session_id'] || s[:session_id]}/#{s['name'] || s[:name]}"
+          when 'l1' then (s['name'] || s[:name]).to_s
+          end
+        end
+
+        # ---- Env helpers ----------------------------------------------------------
+
+        # The .kairos data root. KairosMcp exposes `data_dir` (context_dir/knowledge_dir hang off
+        # it); `kairos_dir` is NOT a real accessor, so data_dir is the correct, test-isolatable base.
+        def kairos_dir
+          if defined?(KairosMcp) && KairosMcp.respond_to?(:data_dir) && KairosMcp.data_dir
+            KairosMcp.data_dir
+          elsif defined?(KairosMcp) && KairosMcp.respond_to?(:kairos_dir)
+            KairosMcp.kairos_dir
+          else
+            File.join(Dir.pwd, '.kairos')
+          end
+        end
+
+        def context_dir
+          if defined?(KairosMcp) && KairosMcp.respond_to?(:context_dir)
+            KairosMcp.context_dir
+          else
+            File.join(kairos_dir, 'context')
+          end
+        end
+
+        def knowledge_dir
+          if defined?(KairosMcp) && KairosMcp.respond_to?(:knowledge_dir)
+            KairosMcp.knowledge_dir
+          else
+            File.join(kairos_dir, 'knowledge')
+          end
+        end
+
+        # ---- Misc -----------------------------------------------------------------
+
+        def slugify(topic)
+          topic.to_s.downcase.strip.gsub(/[^a-z0-9]+/, '_').gsub(/\A_+|_+\z/, '')
+        end
+
+        def extract_frontmatter(content)
+          if content =~ /\A---\n(.*?)\n---/m
+            # Permit Time/Date: a digest's generated_at (or a hand-edited timestamp) may load as
+            # Time; without this the whole frontmatter would silently fail to parse and drop to {}.
+            YAML.safe_load($1, permitted_classes: [Symbol, Time, Date]) || {}
+          else
+            {}
+          end
+        rescue StandardError
+          {}
+        end
+
+        def frontmatter_tags(content)
+          meta = extract_frontmatter(content)
+          Array(meta['tags'] || meta[:tags])
+        end
+
+        def frontmatter_value(content, key)
+          meta = extract_frontmatter(content)
+          meta[key] || meta[key.to_sym]
+        end
+
+        # Tag match tolerant to hyphen/underscore variants (mirrors Scanner normalization).
+        def tag_match?(tags, tag)
+          norm = ->(t) { t.to_s.downcase.tr('-', '_') }
+          target = norm.call(tag)
+          Array(tags).any? { |t| norm.call(t) == target }
+        end
+
+        def context_manager
+          return nil unless defined?(KairosMcp::ContextManager)
+
+          KairosMcp::ContextManager.new
+        end
+
+        def knowledge_provider
+          return nil unless defined?(KairosMcp::KnowledgeProvider)
+
+          KairosMcp::KnowledgeProvider.new
+        end
+
+        def stringify(hash)
+          (hash || {}).each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+        end
+      end
+    end
+  end
+end

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

@@ -8,6 +8,7 @@ require 'time'
 require_relative 'dream/scanner'
 require_relative 'dream/proposer'
 require_relative 'dream/archiver'
+require_relative 'dream/digester'
 
 module Dream
   SKILLSET_ROOT = File.expand_path('..', __dir__)

data/templates/skillsets/dream/skillset.json

@@ -1,16 +1,17 @@
 {
   "name": "dream",
-  "version": "0.2.1",
-  "description": "Memory consolidation and L2 lifecycle management. Scans for recurring patterns, manages L2 soft-archive, and packages promotion proposals.",
+  "version": "0.3.0",
+  "description": "Memory consolidation and L2 lifecycle management. Scans for recurring patterns, manages L2 soft-archive, packages promotion proposals, and generates derived per-topic narrative digests.",
   "author": "Masaomi Hatakeyama",
   "layer": "L1",
   "depends_on": [],
-  "provides": ["pattern_detection", "promotion_discovery", "knowledge_health_scan", "l2_soft_archive", "l2_recall"],
+  "provides": ["pattern_detection", "promotion_discovery", "knowledge_health_scan", "l2_soft_archive", "l2_recall", "narrative_digest"],
   "tool_classes": [
     "KairosMcp::SkillSets::Dream::Tools::DreamScan",
     "KairosMcp::SkillSets::Dream::Tools::DreamPropose",
     "KairosMcp::SkillSets::Dream::Tools::DreamArchive",
-    "KairosMcp::SkillSets::Dream::Tools::DreamRecall"
+    "KairosMcp::SkillSets::Dream::Tools::DreamRecall",
+    "KairosMcp::SkillSets::Dream::Tools::DreamDigest"
   ],
   "config_files": ["config/dream.yml"],
   "knowledge_dirs": ["knowledge/dream_trigger_policy"],

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

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+module KairosMcp
+  module SkillSets
+    module Dream
+      module Tools
+        # dream_digest — derived narrative view over immutable L2/L1 fragments.
+        #
+        # Implements dream_digest_design_v0.4 (FROZEN). A digest is a DERIVED, per-topic,
+        # access-bounded projection that sits BESIDE the fragments and never replaces them.
+        # Synthesis content is generated by an LLM (like dream_propose): `package` builds the
+        # snapshot + a contradiction-preserving directive, `write` persists the LLM output with
+        # provenance, `read` returns it with staleness annotations.
+        class DreamDigest < KairosMcp::Tools::BaseTool
+          def name
+            'dream_digest'
+          end
+
+          def description
+            'Generate/read a DERIVED per-topic narrative digest over L2/L1 fragments. ' \
+              'Never authoritative, never overwrites sources, preserves contradictions, ' \
+              'access-bounded by its sources. Modes: package (snapshot+directive), write (persist ' \
+              'LLM content with provenance), read (with staleness), list.'
+          end
+
+          def category
+            :knowledge
+          end
+
+          def usecase_tags
+            %w[dream digest narrative synthesis derived-view provenance staleness consolidation]
+          end
+
+          def related_tools
+            %w[dream_scan dream_propose dream_archive knowledge_get context_save]
+          end
+
+          def input_schema
+            {
+              type: 'object',
+              properties: {
+                mode: {
+                  type: 'string',
+                  enum: %w[package write read list sweep refresh],
+                  description: 'package (default): snapshot+directive. write: persist LLM content. read: digest+staleness. list: existing digests. sweep: staleness+age health over all digests (schedulable). refresh: fresh regeneration package for a stale topic.'
+                },
+                topic: { type: 'string', description: 'Topic identifier (per-topic partition, I10).' },
+                sources: {
+                  type: 'array',
+                  description: '[package] Explicit READ set. Each: {layer: l2|l1, session_id, name}. Fixes the citable universe (I6). Takes precedence over from_tag.',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      layer: { type: 'string', enum: %w[l2 l1] },
+                      session_id: { type: 'string' },
+                      name: { type: 'string' }
+                    },
+                    required: %w[layer]
+                  }
+                },
+                from_tag: {
+                  type: 'string',
+                  description: '[package] dream_scan->dream_digest wiring: resolve the citable universe (I6) as all live fragments carrying this tag. Used when sources is omitted.'
+                },
+                include_l1: {
+                  type: 'boolean',
+                  description: '[package] When using from_tag, also include L1 entries tagged with it. Default: true.'
+                },
+                snapshot: {
+                  type: 'array',
+                  description: '[write] The snapshot returned by package (the citable universe). Pass through unchanged.',
+                  items: { type: 'object' }
+                },
+                content: { type: 'string', description: '[write] LLM-generated narrative grounded in the snapshot.' },
+                resolved_from: { type: 'string', description: '[write] Optional provenance origin (e.g. "tag:wireup") from package, stored for refresh.' },
+                stale_after_days: { type: 'integer', description: '[sweep] Also flag digests older than this many days as aged.' },
+                directive_id: { type: 'string', description: 'Generation directive identity (I7).' }
+              },
+              required: []
+            }
+          end
+
+          def call(arguments)
+            mode = arguments['mode'] || 'package'
+            digester = KairosMcp::SkillSets::Dream::Digester.new(config: load_dream_config)
+
+            case mode
+            when 'package' then call_package(digester, arguments)
+            when 'write'   then call_write(digester, arguments)
+            when 'read'    then call_read(digester, arguments)
+            when 'list'    then text_content(JSON.pretty_generate(digests: digester.list))
+            when 'sweep'   then call_sweep(digester, arguments)
+            when 'refresh' then call_refresh(digester, arguments)
+            else
+              text_content(JSON.pretty_generate(error: "unknown mode: #{mode}"))
+            end
+          rescue StandardError => e
+            text_content(JSON.pretty_generate(error: e.message, backtrace: e.backtrace&.first(5)))
+          end
+
+          private
+
+          def call_package(digester, arguments)
+            topic = arguments['topic']
+            return text_content(JSON.pretty_generate(error: 'package requires topic')) if topic.nil? || topic.empty?
+
+            result = digester.package(
+              topic: topic,
+              sources: arguments['sources'],
+              from_tag: arguments['from_tag'],
+              include_l1: arguments.fetch('include_l1', true),
+              directive_id: arguments['directive_id']
+            )
+            text_content(format_package(result))
+          end
+
+          def call_write(digester, arguments)
+            # I2: writing a derived digest does not modify L2/L1; gate on L2 modify only if the
+            # host enforces it, but a digest write never touches source content.
+            topic = arguments['topic']
+            return text_content(JSON.pretty_generate(error: 'write requires topic')) if topic.nil? || topic.empty?
+
+            result = digester.write(
+              topic: topic,
+              snapshot: arguments['snapshot'] || [],
+              content: arguments['content'],
+              directive_id: arguments['directive_id'],
+              resolved_from: arguments['resolved_from']
+            )
+            record_generation_event(result)
+            text_content(format_write(result))
+          end
+
+          def call_read(digester, arguments)
+            topic = arguments['topic']
+            return text_content(JSON.pretty_generate(error: 'read requires topic')) if topic.nil? || topic.empty?
+
+            text_content(format_read(digester.read(topic: topic)))
+          end
+
+          def call_sweep(digester, arguments)
+            rows = digester.sweep(stale_after_days: arguments['stale_after_days'])
+            text_content(format_sweep(rows))
+          end
+
+          def call_refresh(digester, arguments)
+            topic = arguments['topic']
+            return text_content(JSON.pretty_generate(error: 'refresh requires topic')) if topic.nil? || topic.empty?
+
+            r = digester.refresh(topic: topic)
+            return text_content("## Dream Digest — refresh: not found (topic: #{topic})") unless r[:found]
+
+            text_content(format_refresh(r))
+          end
+
+          # I7: record the generation EVENT (the derived artifact itself need not be immutable).
+          # The snapshot is recorded with content hashes (not refs alone) and the EFFECTIVE
+          # directive id, both taken from the write result so the record is canonical.
+          def record_generation_event(result)
+            return unless result[:success]
+            return unless defined?(KairosMcp::KairosChain::Chain)
+
+            chain = KairosMcp::KairosChain::Chain.new
+            chain.add_block([{
+              type: 'dream_digest_generation',
+              topic: result[:topic],
+              directive_id: result[:directive_id],
+              output_hash: result[:output_hash],
+              access_bound: result[:access_bound],
+              provenance: Array(result[:provenance]), # {layer, ref, content_hash} per source (I7)
+              provenance_count: result[:provenance_count],
+              generated_at: result[:generated_at]
+            }.to_json])
+          rescue StandardError => e
+            warn "[DreamDigest] Failed to record to blockchain: #{e.message}"
+          end
+
+          def load_dream_config
+            candidates = [dream_user_config_path, dream_template_config_path].compact
+            path = candidates.find { |p| File.exist?(p) }
+            return {} unless path
+
+            YAML.safe_load(File.read(path), permitted_classes: [Symbol]) || {}
+          end
+
+          def dream_user_config_path
+            if defined?(KairosMcp) && KairosMcp.respond_to?(:kairos_dir)
+              File.join(KairosMcp.kairos_dir, 'skillsets', 'dream', 'config', 'dream.yml')
+            else
+              File.join(Dir.pwd, '.kairos', 'skillsets', 'dream', 'config', 'dream.yml')
+            end
+          end
+
+          def dream_template_config_path
+            File.expand_path('../../config/dream.yml', __dir__)
+          end
+
+          # ---- formatting -----------------------------------------------------------
+
+          def format_package(r)
+            lines = []
+            lines << "## Dream Digest — Package (topic: #{r[:topic]})"
+            lines << ""
+            lines << "**Status**: #{r[:status]}"
+            lines << "**Access bound**: #{r[:access_bound]} (I9)"
+            lines << "**Directive id**: #{r[:directive_id]}"
+            lines << "**Resolved from**: #{r[:resolved_from]}" if r[:resolved_from]
+            lines << ""
+            if r[:snapshot].empty?
+              lines << "_No resolvable sources — nothing to digest (I4)._"
+              return lines.join("\n")
+            end
+            lines << "### READ set / citable universe (#{r[:snapshot].size}) — I6"
+            r[:snapshot].each do |s|
+              lines << "- **#{s['ref']}** [#{s['layer']}] hash=`#{s['content_hash'][0, 12]}…` access=#{s['access']}"
+            end
+            lines << ""
+            lines << "### Generation directive (give to LLM, then call mode=write with snapshot+content)"
+            lines << "```"
+            lines << r[:directive].strip
+            lines << "```"
+            lines << ""
+            lines << "### Next step"
+            lines << "```"
+            lines << "dream_digest(mode: \"write\", topic: #{r[:topic].inspect},"
+            lines << "  directive_id: #{r[:directive_id].inspect},"
+            lines << "  snapshot: <the snapshot array above>, content: \"<LLM narrative>\")"
+            lines << "```"
+            lines.join("\n")
+          end
+
+          def format_write(r)
+            lines = []
+            lines << "## Dream Digest — Written (topic: #{r[:topic]})"
+            lines << ""
+            lines << "**Path**: #{r[:path]}"
+            lines << "**Output hash**: `#{r[:output_hash]}`"
+            lines << "**Provenance count**: #{r[:provenance_count]}"
+            lines << "**Access bound**: #{r[:access_bound]} (I9)"
+            lines << "**Generated at**: #{r[:generated_at]}"
+            lines << ""
+            lines << "_Derived view (I1/I8): not authoritative, regenerable, no write-back to L2/L1._"
+            lines.join("\n")
+          end
+
+          def format_read(r)
+            return "## Dream Digest — not found (topic: #{r[:topic]})" unless r[:found]
+
+            lines = []
+            lines << "## Dream Digest (topic: #{r[:topic]})"
+            lines << ""
+            stale_marker = r[:stale] ? "⚠️ STALE" : "fresh"
+            lines << "**Status**: #{stale_marker}"
+            lines << "**Access bound**: #{r[:access_bound]} (I9)"
+            lines << "**Generated at**: #{r[:generated_at]} (#{r[:age_days]}d ago)"
+            lines << "**Provenance count**: #{r[:provenance_count]}"
+            if r[:stale]
+              lines << ""
+              lines << "### Drifted sources (I5 — labelled, not corrected; regenerate to refresh)"
+              r[:drifted].each { |d| lines << "- **#{d['ref']}**: #{d['reason']}" }
+            end
+            lines << ""
+            lines << "---"
+            lines << ""
+            lines << r[:content]
+            lines.join("\n")
+          end
+
+          def format_sweep(rows)
+            lines = []
+            lines << "## Dream Digest — Sweep (#{rows.size} digest(s))"
+            lines << ""
+            if rows.empty?
+              lines << "_No digests yet._"
+              return lines.join("\n")
+            end
+            needs = rows.count { |r| r[:needs_refresh] }
+            lines << "**Needs refresh**: #{needs} / #{rows.size}"
+            lines << ""
+            lines << "| topic | status | drifted | age(d) | access |"
+            lines << "|---|---|---|---|---|"
+            rows.each do |r|
+              status = r[:stale] ? "⚠️ stale" : (r[:aged] ? "aged" : "fresh")
+              lines << "| #{r[:topic]} | #{status} | #{r[:drifted_count]} | #{r[:age_days]} | #{r[:access_bound]} |"
+            end
+            lines << ""
+            lines << "_Scheduling note: an external trigger (cron / Claude Code hook / autonomous loop) "
+            lines << "calls sweep, then `refresh` + `write` per needs_refresh topic. dream does not "
+            lines << "schedule itself (separate layer)._"
+            lines.join("\n")
+          end
+
+          def format_refresh(r)
+            lines = []
+            lines << "## Dream Digest — Refresh package (topic: #{r[:topic]})"
+            lines << ""
+            lines << "**Status**: #{r[:status]} (prior age: #{r[:prior_age_days]}d)"
+            lines << "**Access bound**: #{r[:access_bound]} (I9)"
+            lines << "**Dropped (no longer resolvable, omitted per I4)**: #{r[:dropped].empty? ? 'none' : r[:dropped].join(', ')}"
+            lines << ""
+            if r[:snapshot].empty?
+              lines << "_All sources gone — nothing to regenerate (I4). Consider deleting the stale digest._"
+              return lines.join("\n")
+            end
+            lines << "### Fresh READ set / citable universe (#{r[:snapshot].size}) — I6"
+            r[:snapshot].each do |s|
+              lines << "- **#{s['ref']}** [#{s['layer']}] hash=`#{s['content_hash'][0, 12]}…`"
+            end
+            lines << ""
+            lines << "### Regeneration directive (give to LLM, then mode=write with this snapshot)"
+            lines << "```"
+            lines << r[:directive].strip
+            lines << "```"
+            lines.join("\n")
+          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.29.6
+  version: 3.30.0
 platform: ruby
 authors:
 - Masaomi Hatakeyama
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-05 00:00:00.000000000 Z
+date: 2026-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -366,10 +366,12 @@ files:
 - templates/skillsets/dream/knowledge/dream_trigger_policy/dream_trigger_policy.md
 - templates/skillsets/dream/lib/dream.rb
 - templates/skillsets/dream/lib/dream/archiver.rb
+- templates/skillsets/dream/lib/dream/digester.rb
 - templates/skillsets/dream/lib/dream/proposer.rb
 - templates/skillsets/dream/lib/dream/scanner.rb
 - templates/skillsets/dream/skillset.json
 - templates/skillsets/dream/tools/dream_archive.rb
+- templates/skillsets/dream/tools/dream_digest.rb
 - templates/skillsets/dream/tools/dream_propose.rb
 - templates/skillsets/dream/tools/dream_recall.rb
 - templates/skillsets/dream/tools/dream_scan.rb