kairos-chain 3.24.3 → 3.24.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb099806eedb198afc167cbb810110ab7bffac2fceea3684eb14a24e3e7b46fb
-  data.tar.gz: 61223eff1c6cd146eea47d44ab0ee95506a8baa6e15a0f1f5c2e929e9d44a5b1
+  metadata.gz: 98d111b116bdd82edadfd6b634d551bee42e289698ecf20f4fd4e60d8d0a9b2f
+  data.tar.gz: 3f4ffc6049f6e5e1be2dc5f8238308b2680f08f7a110218d26b1d1a69d296810
 SHA512:
-  metadata.gz: 91d4a86fc2df06025fefb5f0252e9f019d85cb9fc31f6ceec0d2e0bbe1209c8d24277e7448faace8ced8ba28c889dee0af7f68fbf50d6dda6da27bbb3366e588
-  data.tar.gz: b6847081bc03d40d2ae77ec317d52955ba7fdc2597b91d10addba2a052067339171542316810d8e1dc95c5f4eb35eb5963425f7f82961ae13bbc5e3bfa8e2f50
+  metadata.gz: ad44f0bf58d272ff80d7a50e09a0f93634e9496b6e6238f8311838e08109463e614ee05f2356b7f311c6538c1e0511ae44bfe0c122bab828d05e6888de042bfa
+  data.tar.gz: 4b1995339b02160c87636f520cc33e58667a45d8081092d7fa480ec6b6e300baddd3248ed76483f89253440299a25b60d497b4ed3fc3ac566769fa8d20ed632b

data/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.24.9] - 2026-05-05
+
+### Added (L1 knowledge: goal_setting_heuristic)
+
+新規 L1 knowledge skill `goal_setting_heuristic` v0.2 を追加（`templates/knowledge/goal_setting_heuristic/`）。
+
+Knowledge Ethos v2.0（自律 agent ガードレールのフル版）が round 2 multi-LLM review で REVISE 判定 + 哲学 / 運用の根本レベル混乱が露見し塩漬けになったため、その核心 3 機能（Telos 多元性 / Boundary 監視 / Contradiction 許容）だけを抜き出した軽量代替として位置づけ。
+
+主な内容:
+- 3 階層 (Mission / Milestone / Action) + branch (Primary / Fallback / Pivot) の goal 構造
+- Goal-set 時の 3 つの自問（telos / boundary / contradiction）
+- 動的改訂トリガ 6 種（rolling window bias 検出を含む）
+- 完了 / 失敗時の next-step 提案 (halt 禁止) と halt 許可条件 3 種
+- Mission = blocking、Milestone/Action = non-blocking 区分
+- Rolling + 週次の振り返り集計
+- 既存 KairosChain ツール (`dream_*`, `introspection_check`, `multi_llm_review`, `skills_promote`, `context_save`, `chain_record`) との soft / hard 強制度区分明示
+
+軽量レビュー (1 round, 5 reviewer, persona 2 体): 1 APPROVE / 3 REJECT / 1 REVISE。critical P0 8 件を v0.2 で反映済み。塩漬け中の Knowledge Ethos v2.0 とは別アーティファクトとして並存。
+
+### Changed
+- `KairosMcp::VERSION` 3.24.8 → 3.24.9
+
 ## [3.24.1] - 2026-04-27
 
 ### Fixed (multi_llm_review_wait)

data/lib/kairos_mcp/anthropic_skill_parser.rb

@@ -2,6 +2,7 @@
 
 require 'yaml'
 require 'fileutils'
+require 'securerandom'
 
 module KairosMcp
   # AnthropicSkillParser: Parses Anthropic skills format (YAML frontmatter + Markdown)
@@ -101,7 +102,7 @@ module KairosMcp
         FileUtils.mkdir_p(skill_dir)
 
         md_file = File.join(skill_dir, "#{name}.md")
-        File.write(md_file, content)
+        atomic_write(md_file, content)
 
         if create_subdirs
           FileUtils.mkdir_p(File.join(skill_dir, 'scripts'))
@@ -121,10 +122,27 @@ module KairosMcp
         md_file = find_md_file(skill_dir)
         raise "No markdown file found in #{skill_dir}" unless md_file
 
-        File.write(md_file, new_content)
+        atomic_write(md_file, new_content)
         parse(skill_dir)
       end
 
+      # Atomic-rename write. Tempfile in same directory then File.rename to
+      # the target. Crash mid-write leaves target either fully replaced or
+      # untouched — never truncated. Security-grounded (don't destroy
+      # someone else's valid record), not durability-grounded.
+      def atomic_write(target_path, content)
+        dir = File.dirname(target_path)
+        FileUtils.mkdir_p(dir) unless File.directory?(dir)
+        tempname = "#{File.basename(target_path)}.tmp.#{Process.pid}.#{SecureRandom.hex(4)}"
+        temp_path = File.join(dir, tempname)
+        begin
+          File.write(temp_path, content)
+          File.rename(temp_path, target_path)
+        ensure
+          File.delete(temp_path) if File.exist?(temp_path)
+        end
+      end
+
       # List all scripts in a skill
       #
       # @param skill [SkillEntry] The skill entry

data/lib/kairos_mcp/capability.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module KairosMcp
+  # Capability module — Phase 1.5 self-articulation infrastructure.
+  #
+  # Design reference: docs/drafts/capability_boundary_design_v1.1.md
+  #
+  # Provides:
+  # - active_harness detection (env_var first, auto-detect fallback, :unknown honest)
+  # - harness_requirement metadata normalization
+  # - manifest aggregation across BaseTool subclasses
+  #
+  # 8 invariants govern this module:
+  #   1. Self-articulation     — boundary must be queryable at runtime
+  #   2. Honest unknown        — :unknown beats false guess
+  #   3. Declare-not-enforce   — articulation only, no runtime gate
+  #   4. Structural congruence — DSL matches existing BaseTool method override pattern
+  #   5. Composability         — SkillSet tools participate equally
+  #   6. Active vs external separation (with same-source exclusion)
+  #   7. Forward-only metadata — opt-in, with declared:true/false in manifest
+  #   8. Acknowledgment         — runtime dependence is articulated, not silently absorbed
+  module Capability
+    TIERS = %i[core harness_assisted harness_specific].freeze
+
+    # Mapping from active_harness symbol to its "same-source" CLI name.
+    # When active_harness=:claude_code and a tool declares requires_externals: [:claude_cli],
+    # claude_cli is excluded from used_externals because it is the SAME source as the
+    # harness running KairosChain (active vs external separation invariant).
+    SAME_SOURCE_CLI = {
+      claude_code: :claude_cli,
+      codex_cli:   :codex_cli,
+      cursor:      :cursor_cli
+    }.freeze
+
+    class << self
+      # Returns active_harness detection result. Cached at process boot.
+      #
+      # @return [Hash] { active_harness:, detection_method:, confidence: }
+      def detect_harness
+        @detection ||= compute_detection
+      end
+
+      # Test-only escape hatch. Production code never calls this.
+      def reset!
+        @detection = nil
+      end
+
+      # Normalize a tool's harness_requirement return value to canonical Hash form.
+      # Symbol → { tier: <symbol> }
+      # Hash   → validated Hash (raises ArgumentError on violation)
+      def normalize_requirement(value)
+        hash = case value
+               when Symbol then { tier: value }
+               when Hash   then deep_symbolize(value)
+               else
+                 raise ArgumentError, "harness_requirement must be Symbol or Hash, got #{value.class}"
+               end
+
+        validate!(hash)
+        hash
+      end
+
+      # Aggregate harness_requirement declarations across all registered tools.
+      # Skip + warn on per-tool validation failure (partial-failure policy).
+      #
+      # @param registry [KairosMcp::ToolRegistry]
+      # @return [Hash] { tools: [...], summary: {...}, declaration_errors: [...] }
+      def aggregate_manifest(registry)
+        tools_index = registry.instance_variable_get(:@tools) || {}
+        sources = registry.instance_variable_get(:@tool_sources) || {}
+
+        entries = []
+        errors = []
+        summary = Hash.new(0)
+
+        tools_index.each do |name, tool|
+          source = sources[name] || :core_tool
+          # declared = explicitly overridden in tool subclass (vs inherited BaseTool default)
+          declared = tool.method(:harness_requirement).owner != KairosMcp::Tools::BaseTool
+          raw = safe_call_requirement(tool)
+
+          begin
+            normalized = normalize_requirement(raw)
+            entry = { name: name, declared: declared, source: source }.merge(normalized)
+            entries << entry
+            tier_key = declared ? normalized[:tier] : :"undeclared_default_#{normalized[:tier]}"
+            summary[tier_key] += 1
+          rescue ArgumentError => e
+            errors << { tool: name, issue: "invalid harness_requirement: #{e.message}",
+                        severity: :declaration_error }
+            entries << { name: name, declared: false, source: source, tier: :unknown,
+                         declaration_error: e.message }
+            summary[:declaration_errors] += 1
+          end
+        end
+
+        { tools: entries, summary: summary.transform_values(&:to_i),
+          declaration_errors: errors }
+      end
+
+      # which-style PATH check using only filesystem (no subprocess).
+      # Returns true/false.
+      def cli_in_path?(name)
+        return false unless name.is_a?(Symbol) || name.is_a?(String)
+        bin = name.to_s
+        ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).any? do |dir|
+          full = File.join(dir, bin)
+          File.executable?(full) && !File.directory?(full)
+        end
+      end
+
+      # Get version of a CLI by spawning subprocess (only when probe_versions: true).
+      # Returns nil on any failure (Honest unknown).
+      def cli_version(name)
+        return nil unless cli_in_path?(name)
+        out = `#{name} --version 2>&1`.strip
+        $?.success? ? out.lines.first&.strip : nil
+      rescue StandardError
+        nil
+      end
+
+      # Compute used_externals from declared manifest entries given active_harness.
+      # Applies same-source exclusion rule.
+      def compute_used_externals(manifest_entries, active_harness)
+        same_source = SAME_SOURCE_CLI[active_harness]
+        union = manifest_entries.flat_map { |e| Array(e[:requires_externals]) }.uniq
+        excluded = same_source && union.include?(same_source) ? [same_source] : []
+        {
+          value: union - excluded,
+          same_source_excluded: excluded
+        }
+      end
+
+      private
+
+      def compute_detection
+        env = ENV['KAIROS_HARNESS']
+        if env && !env.empty?
+          if env =~ /\A[A-Za-z0-9_\-]{1,64}\z/
+            return { active_harness: env.to_sym, detection_method: :env_var, confidence: :explicit }
+          else
+            warn "[Capability] KAIROS_HARNESS=#{env.inspect} is malformed; falling back to :unknown"
+            return { active_harness: :unknown, detection_method: :none, confidence: :unknown }
+          end
+        end
+
+        if (auto = auto_detect)
+          { active_harness: auto, detection_method: :auto_detect, confidence: :inferred }
+        else
+          { active_harness: :unknown, detection_method: :none, confidence: :unknown }
+        end
+      end
+
+      # Auto-detect harness from harness-native signals only.
+      # CWD markers (CLAUDE.md, MEMORY.md) are intentionally NOT used because
+      # they are project artifacts, not harness signatures (would re-introduce
+      # conflation that Phase 1.5 is meant to remove).
+      def auto_detect
+        # Claude Code sets several env vars when running. Check for any.
+        return :claude_code if ENV.keys.any? { |k| k.start_with?('CLAUDE_CODE_') || k == 'CLAUDECODE' }
+        # Codex CLI / Cursor specific env vars (heuristic; may be empty in practice).
+        return :codex_cli if ENV.key?('CODEX_CLI') || ENV.key?('CODEX_AGENT_ID')
+        return :cursor    if ENV.key?('CURSOR_AGENT') || ENV.key?('CURSOR_TRACE_ID')
+        nil
+      end
+
+      def deep_symbolize(hash)
+        hash.each_with_object({}) do |(k, v), out|
+          key = k.is_a?(String) ? k.to_sym : k
+          out[key] = case v
+                     when Hash then deep_symbolize(v)
+                     when Array then v.map { |item| item.is_a?(Hash) ? deep_symbolize(item) : item }
+                     else v
+                     end
+        end
+      end
+
+      def validate!(hash)
+        tier = hash[:tier]
+        unless TIERS.include?(tier)
+          raise ArgumentError, "tier must be one of #{TIERS.inspect}, got #{tier.inspect}"
+        end
+
+        if tier == :harness_specific && hash[:target_harness].nil?
+          raise ArgumentError, "harness_specific tier requires :target_harness"
+        end
+
+        Array(hash[:requires_harness_features]).each_with_index do |entry, idx|
+          unless entry.is_a?(Hash) && entry[:feature] && entry[:target_harness]
+            raise ArgumentError, "requires_harness_features[#{idx}] missing :feature or :target_harness"
+          end
+        end
+
+        Array(hash[:fallback_chain]).each_with_index do |entry, idx|
+          unless entry.is_a?(Hash) && entry[:path] && entry[:tier] && entry[:condition]
+            raise ArgumentError, "fallback_chain[#{idx}] missing :path/:tier/:condition"
+          end
+          if entry[:tier] == :harness_specific && entry[:target_harness].nil?
+            raise ArgumentError, "fallback_chain[#{idx}] tier=:harness_specific requires :target_harness"
+          end
+        end
+
+        nil
+      end
+
+      def safe_call_requirement(tool)
+        tool.harness_requirement
+      rescue StandardError => e
+        raise ArgumentError, "tool raised during harness_requirement: #{e.message}"
+      end
+    end
+
+  end
+end

data/lib/kairos_mcp/context_graph.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'fileutils'
+require 'securerandom'
+require 'time'
+require 'yaml'
+
+module KairosMcp
+  # ContextGraph: Phase 1 minimal mapping for L2 informed_by edges.
+  #
+  # Design reference: docs/drafts/context_graph_l2_mapping_design_v2.1.md
+  #
+  # Responsibilities:
+  #   - target string parse (TARGET_RE)
+  #   - resolve_target: path containment + symlink rejection (security)
+  #   - relations array validation (shape + type whitelist)
+  #
+  # Non-responsibilities (by design, L2-evidential):
+  #   - durability invariants (write serialization, fsync sequence) — not L2's job
+  #   - semantic validation (whether informed_by claim is true) — defer to traverser
+  #   - edges.jsonl cache — Phase 2 if observation justifies
+  module ContextGraph
+    # Recognized edge types in Phase 1. Unknown types are accepted on write
+    # (forward-compat) but skipped on traverse.
+    KNOWN_TYPES = %w[informed_by].freeze
+
+    # Target canonical regex (v2.1 §2). Permissive enough to reference both
+    # canonical session_ids (session_<8>_<6>_<8hex>) and the human-readable
+    # forms already on disk (e.g. coaching_insights_20260327, received_skills).
+    # Leading char restricted to [A-Za-z0-9_] to forbid dot/hyphen path tricks.
+    TARGET_RE = /\Av1:(?<sid>[A-Za-z0-9_][A-Za-z0-9_.\-]{0,127})\/(?<name>[A-Za-z0-9_][A-Za-z0-9_.\-]{0,127})\z/.freeze
+
+    # YAML value types permitted inside relations[] items.
+    # Anything outside this set is rejected on write to keep YAML.dump
+    # output free of anchors/aliases that downstream non-safe loaders
+    # could exploit.
+    SAFE_VALUE_TYPES = [
+      String, Integer, Float, TrueClass, FalseClass, NilClass,
+      Hash, Array, Time, Date
+    ].freeze
+
+    DEFAULT_MAX_DEPTH = 3
+    MAX_DEPTH_CLAMP = 16
+    # Recursion depth cap for assert_safe_value!. Pathological deeply-nested
+    # YAML in user-supplied frontmatter can otherwise blow Ruby's call stack
+    # (SystemStackError) before validation completes. 32 is well above any
+    # legitimate usage and far below Ruby's default stack limit.
+    MAX_VALUE_NESTING = 32
+
+    # Error hierarchy. All inherit from a single base so callers can
+    # rescue ContextGraph::Error to surface uniformly.
+    class Error < StandardError; end
+    class MalformedTargetError < Error; end
+    class MalformedRelationsError < Error; end
+    class UnsafeRelationValueError < Error; end
+    class PathEscapeError < Error; end
+    class SymlinkRejectedError < Error; end
+    class PathResolutionError < Error; end
+    class InvalidFrontmatterError < Error; end
+
+    module_function
+
+    # Parse a target string into {sid, name}. Returns nil on mismatch.
+    def parse_target(target_str)
+      return nil unless target_str.is_a?(String)
+
+      m = TARGET_RE.match(target_str)
+      return nil unless m
+
+      { sid: m[:sid], name: m[:name] }
+    end
+
+    # Resolve target to an on-disk file path with full security checks.
+    #
+    # @param target_str [String] e.g. "v1:session_xxx/name"
+    # @param context_root [String] absolute path to L2 context root
+    # @return [Hash] { path: String|nil, status: :ok|:dangling }
+    # @raise MalformedTargetError, PathEscapeError, SymlinkRejectedError, PathResolutionError
+    def resolve_target(target_str, context_root)
+      parsed = parse_target(target_str)
+      raise MalformedTargetError, "target does not match canonical form: #{target_str.inspect}" unless parsed
+
+      root_real = begin
+        File.realpath(context_root)
+      rescue Errno::ENOENT
+        # context_root itself is missing — treat as resolution failure
+        raise PathResolutionError, "context_root does not exist: #{context_root}"
+      end
+
+      candidate = File.join(root_real, parsed[:sid], parsed[:name], "#{parsed[:name]}.md")
+
+      # Symlink rejection BEFORE realpath: lstat does not follow links, so
+      # if the final component is a symlink we reject it here without
+      # leaking the symlink's target into containment evaluation.
+      lst = begin
+        File.lstat(candidate)
+      rescue Errno::ENOENT
+        # Forward reference: target file does not exist yet.
+        verify_dangling_containment(candidate, root_real)
+        return { path: nil, status: :dangling }
+      rescue SystemCallError => e
+        raise PathResolutionError, "fs error stat'ing #{target_str}: #{e.message}"
+      end
+
+      raise SymlinkRejectedError, "target final component is a symlink: #{candidate}" if lst.symlink?
+
+      resolved = begin
+        File.realpath(candidate)
+      rescue SystemCallError => e
+        raise PathResolutionError, "fs error resolving #{target_str}: #{e.message}"
+      end
+
+      sep = File::SEPARATOR
+      unless resolved == root_real || resolved.start_with?(root_real + sep)
+        raise PathEscapeError, "resolved path escapes context_root: #{resolved}"
+      end
+
+      { path: resolved, status: :ok }
+    end
+
+    # Validate a relations[] array on the write path. Mutates nothing.
+    # Returns nil on success, raises on the first violation.
+    #
+    # Rules (v2.1 §1.1, §4.2):
+    #   - relations is Array
+    #   - each item is Hash with String type and String target
+    #   - target matches TARGET_RE
+    #   - all values are SAFE_VALUE_TYPES (recursively)
+    def validate_relations!(relations)
+      raise MalformedRelationsError, 'relations must be an Array' unless relations.is_a?(Array)
+
+      relations.each_with_index do |item, idx|
+        raise MalformedRelationsError, "relations[#{idx}] must be a Hash" unless item.is_a?(Hash)
+
+        type = item['type'] || item[:type]
+        target = item['target'] || item[:target]
+
+        raise MalformedRelationsError, "relations[#{idx}] missing 'type'" if type.nil?
+        raise MalformedRelationsError, "relations[#{idx}] missing 'target'" if target.nil?
+        raise MalformedRelationsError, "relations[#{idx}].type must be String" unless type.is_a?(String)
+        raise MalformedRelationsError, "relations[#{idx}].target must be String" unless target.is_a?(String)
+        raise MalformedTargetError, "relations[#{idx}].target does not match canonical form: #{target.inspect}" unless TARGET_RE.match?(target)
+
+        item.each do |k, v|
+          assert_safe_value!(v, "relations[#{idx}].#{k}", 0)
+        end
+      end
+
+      nil
+    end
+
+    # Recursively check that a value tree contains only SAFE_VALUE_TYPES.
+    # Bounded by MAX_VALUE_NESTING to prevent SystemStackError from
+    # pathological frontmatter input.
+    def assert_safe_value!(value, location, depth)
+      raise UnsafeRelationValueError, "value nesting exceeds MAX_VALUE_NESTING=#{MAX_VALUE_NESTING} at #{location}" if depth > MAX_VALUE_NESTING
+
+      case value
+      when Hash
+        value.each do |k, v|
+          assert_safe_value!(k, "#{location}.<key>", depth + 1)
+          assert_safe_value!(v, "#{location}.#{k}", depth + 1)
+        end
+      when Array
+        value.each_with_index { |v, i| assert_safe_value!(v, "#{location}[#{i}]", depth + 1) }
+      else
+        return if SAFE_VALUE_TYPES.any? { |t| value.is_a?(t) }
+
+        raise UnsafeRelationValueError,
+              "unsafe value type #{value.class} at #{location} (allowed: #{SAFE_VALUE_TYPES.map(&:name).join(', ')})"
+      end
+    end
+
+    # Atomic write: create tempfile in same directory, write, rename.
+    # Replaces target with full content. Crash mid-write leaves target
+    # either pre- or post-rename (never truncated).
+    #
+    # @param target_path [String] file to replace
+    # @param content [String] full file content
+    def atomic_write(target_path, content)
+      dir = File.dirname(target_path)
+      FileUtils.mkdir_p(dir) unless File.directory?(dir)
+
+      tempname = "#{File.basename(target_path)}.tmp.#{Process.pid}.#{SecureRandom.hex(4)}"
+      temp_path = File.join(dir, tempname)
+
+      begin
+        File.write(temp_path, content)
+        File.rename(temp_path, target_path)
+      ensure
+        File.delete(temp_path) if File.exist?(temp_path)
+      end
+    end
+
+    # Check that the parent directory of a missing target stays inside root.
+    # Used for the dangling (ENOENT) branch.
+    def verify_dangling_containment(candidate, root_real)
+      # Walk up until we find an existing ancestor
+      ancestor = candidate
+      until File.exist?(ancestor)
+        parent = File.dirname(ancestor)
+        break if parent == ancestor # reached fs root
+        ancestor = parent
+      end
+
+      return unless File.exist?(ancestor)
+
+      ancestor_real = File.realpath(ancestor)
+      sep = File::SEPARATOR
+      return if ancestor_real == root_real || ancestor_real.start_with?(root_real + sep)
+
+      raise PathEscapeError, "dangling target's nearest ancestor escapes context_root: #{ancestor_real}"
+    end
+
+    # BFS traverse informed_by edges starting from (start_sid, start_name).
+    #
+    # @param start_sid [String]
+    # @param start_name [String]
+    # @param context_root [String]
+    # @param max_depth [Integer]
+    # @return [Hash] { root:, nodes: [...], warnings: [...] }
+    def traverse_informed_by(start_sid:, start_name:, context_root:, max_depth: DEFAULT_MAX_DEPTH)
+      depth_limit = sanitize_max_depth(max_depth)
+      root_target = "v1:#{start_sid}/#{start_name}"
+      result = { root: root_target, nodes: [], warnings: [] }
+      visited = {}
+
+      queue = [[root_target, 0]]
+
+      until queue.empty?
+        target, depth = queue.shift
+        next if visited.key?(target)
+
+        visited[target] = true
+
+        node = visit_node(target, context_root, result[:warnings])
+        node[:depth] = depth
+        result[:nodes] << node
+
+        next if node[:status] != :ok
+        next if depth >= depth_limit
+
+        outgoing = read_relations(node[:path], result[:warnings])
+        outgoing.each_with_index do |edge, idx|
+          unless edge.is_a?(Hash)
+            result[:warnings] << "skip relations item #{idx} of #{node[:target]}: not a Hash"
+            next
+          end
+          next unless edge['type'] == 'informed_by' || edge[:type] == 'informed_by'
+          edge_target = edge['target'] || edge[:target]
+          next unless edge_target.is_a?(String)
+          next if visited.key?(edge_target)
+
+          queue << [edge_target, depth + 1]
+        end
+      end
+
+      result
+    end
+
+    # Coerce caller-supplied max_depth into [0, MAX_DEPTH_CLAMP]. Non-Integer
+    # input falls back to DEFAULT_MAX_DEPTH (avoids ArgumentError /
+    # NoMethodError on string or nil from tool args).
+    def sanitize_max_depth(value)
+      n = Integer(value) rescue DEFAULT_MAX_DEPTH
+      return 0 if n < 0
+      [n, MAX_DEPTH_CLAMP].min
+    end
+
+    # Visit one node: resolve, classify status. Returns node hash.
+    def visit_node(target, context_root, warnings)
+      resolved = resolve_target(target, context_root)
+      if resolved[:status] == :dangling
+        return { target: target, status: :dangling, reason: nil, path: nil }
+      end
+
+      { target: target, status: :ok, reason: nil, path: resolved[:path] }
+    rescue MalformedTargetError => e
+      warnings << "skip #{target}: malformed (#{e.message})"
+      { target: target, status: :skipped, reason: 'malformed', path: nil }
+    rescue PathResolutionError => e
+      warnings << "skip #{target}: path_resolution (#{e.message})"
+      { target: target, status: :skipped, reason: 'path_resolution', path: nil }
+      # PathEscapeError and SymlinkRejectedError intentionally NOT caught:
+      # those are hard fails on both write and read paths (v2.1 §3.1).
+    end
+
+    # Read a node's relations[] for traversal. Returns [] on any read-side
+    # issue (parse fail, missing schema, unknown schema), appending a warning.
+    def read_relations(md_path, warnings)
+      return [] unless md_path && File.exist?(md_path)
+
+      content = File.read(md_path, encoding: 'UTF-8')
+      m = content.match(/\A---\r?\n(.+?)\r?\n---\r?\n/m)
+      return [] unless m
+
+      begin
+        # permitted_classes intentionally symmetric with write-side
+        # SAFE_VALUE_TYPES (no Symbol). Legacy files containing Symbol values
+        # parse-fail loudly here rather than feed asymmetric data into BFS.
+        front = YAML.safe_load(m[1], permitted_classes: [Date, Time]) || {}
+      rescue StandardError => e
+        warnings << "skip relations of #{md_path}: parse_failed (#{e.message})"
+        return []
+      end
+
+      unless front.is_a?(Hash)
+        warnings << "skip relations of #{md_path}: frontmatter root is not a Hash (got #{front.class})"
+        return []
+      end
+
+      schema_v = front['relations_schema'] || front[:relations_schema]
+      if schema_v && schema_v != 1
+        warnings << "skip relations of #{md_path}: unknown_schema_version=#{schema_v.inspect}"
+        return []
+      end
+
+      rels = front['relations'] || front[:relations]
+      return [] unless rels.is_a?(Array)
+
+      rels
+    end
+  end
+end