kairos-chain 3.24.9 → 3.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98d111b116bdd82edadfd6b634d551bee42e289698ecf20f4fd4e60d8d0a9b2f
-  data.tar.gz: 3f4ffc6049f6e5e1be2dc5f8238308b2680f08f7a110218d26b1d1a69d296810
+  metadata.gz: 31f36e0972d3b7f0848a2a5334d18e5dce69ca4e9f507d0e8072ca9b263983b8
+  data.tar.gz: 3d4c0ff8590721b645088b386e2d3acfc7944fae62b774776a4fd2f4f65887ab
 SHA512:
-  metadata.gz: ad44f0bf58d272ff80d7a50e09a0f93634e9496b6e6238f8311838e08109463e614ee05f2356b7f311c6538c1e0511ae44bfe0c122bab828d05e6888de042bfa
-  data.tar.gz: 4b1995339b02160c87636f520cc33e58667a45d8081092d7fa480ec6b6e300baddd3248ed76483f89253440299a25b60d497b4ed3fc3ac566769fa8d20ed632b
+  metadata.gz: 781cc48a6a9e55de327e2ca7cf4bee5d1e195dc9dc4c8f86e7998e36dc2d93ac301bd17c60efcacb0b63d4347d352c83c365d24cc7415e2f319f3a7276741c19
+  data.tar.gz: 7f91d5619741e422a6594bddb22a8bfba4bacf31de8681424e46a91c5a7ffa3b71d1d5ecaf21306a66680db0136efe252744e9dc9ae5be3446a8d50916b8e306

data/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.25.0] - 2026-05-07
+
+### Added (Instruction mode projection)
+
+`plugin_projector` SkillSet に新しい artifact type `instruction_mode` を追加。アクティブな instruction mode 本体（`.kairos/skills/<active_mode>.md`）を `.claude/kairos/instruction_mode.md` に flat 投射し、project-root `CLAUDE.md` にマネージドな `@`-import 領域を merge することで、parent / `claude -p` subprocess / Agent tool sub-agent の 3 surface すべてに mode 本体を配信。
+
+主な動機 (Theme A/A-2/A-3 検証ログ参照):
+- MCP `instructions` channel は Claude Code harness によって途中で truncated され mode 本体の規範部分が届かない
+- Agent tool sub-agent は MCP `instructions` を**一切継承しない**ため、Persona Agent team が masa mode 不在で動作してきた（Prop 5 違反）
+- CLAUDE.md `@`-import は parent + subprocess + sub-agent の 3 surface に対し 107KB まで欠損なく配信することを Opus 4.6 / 4.7 で実証
+
+主な変更:
+- 新 CLI subcommand `kairos-chain mode {project|status|remove}` (`bin/kairos-chain`)
+- `KairosMcp::PluginProjector#project_instruction_mode!` / `#remove_projected_instruction_mode!` / `#instruction_mode_status` 追加 (`lib/kairos_mcp/plugin_projector.rb`)
+- `Protocol#load_instructions` 三状態化:
+  - 投射済み → slim identity + pointer payload
+  - 未投射 → 既存 full body の冒頭に first-run setup notice を prepend し、LLM がユーザーをセットアップに自動案内できるようにする
+  - `mode == 'none'` → nil（既存動作）
+- `.kairos/instruction_mode_manifest.json` で投射状態を track（既存 `projection_manifest.json.outputs` と独立、`verify` への副作用なし）
+
+Out of scope (既存 `plugin_projector` と同 scope):
+- 1 プロジェクトに複数の KairosChain インスタンス
+- `.git` 共有の git worktree
+- 並行 projector プロセス
+- 第三者による `CLAUDE.md` 書き換えからの自動回復
+- projector 自身の self-projection（Prop 1 自己言及性、open philosophical question）
+
+サイズ policy: 150KB warn / 256KB refuse。
+
+設計 (round 4 multi-LLM review converged):
+- `log/20260506_plugin_projector_instance_mode_extension_v4_accepted_design.md`
+- `log/20260507_plugin_projector_instruction_mode_implementation_plan.md`
+
+### Changed
+- `KairosMcp::VERSION` 3.24.9 → 3.25.0
+
 ## [3.24.9] - 2026-05-05
 
 ### Added (L1 knowledge: goal_setting_heuristic)

data/README.md

@@ -20,6 +20,7 @@ A self-referential [Model Context Protocol (MCP)](https://modelcontextprotocol.i
 - **Attestation System (Synoptis)** — Cryptographic attestation and trust scoring
 - **Dream Mode** — Speculative knowledge proposals with community review
 - **Claude Code Plugin Projection** — Auto-project SkillSets as Claude Code plugins (hooks, agents, slash commands)
+- **Instruction Mode Projection** — Project the active instruction mode body to project-root `CLAUDE.md` via a managed `@`-import region; reaches Agent tool sub-agents (which do not receive MCP `instructions`) and bypasses the harness truncation cap
 - **Multi-LLM Review** — Parallel dispatch to heterogeneous LLMs (Claude, Codex, Cursor) via CLI subprocesses; consensus verdict with aggregated findings
 
 ## Installation
@@ -61,6 +62,9 @@ kairos-chain skillset list         # List installed SkillSets
 kairos-chain skillset install PATH # Install a SkillSet from path
 kairos-chain skillset enable NAME  # Enable a SkillSet
 kairos-chain skillset info NAME    # Show SkillSet details
+kairos-chain mode project          # Project active instruction mode to CLAUDE.md
+kairos-chain mode status           # Show instruction mode projection state
+kairos-chain mode remove           # Remove instruction mode projection
 kairos-chain -v                    # Show version
 ```
 

data/bin/kairos-chain

@@ -342,6 +342,97 @@ when 'upgrade'
     puts content[:text] if content[:type] == 'text'
   end
   exit
+
+when 'mode'
+  ARGV.shift # Remove 'mode' from ARGV
+
+  mode_action = ARGV.shift || 'project'
+
+  $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+  require 'kairos_mcp'
+
+  # Honor --data-dir if present anywhere in remaining ARGV
+  if (idx = ARGV.index('--data-dir'))
+    KairosMcp.data_dir = File.expand_path(ARGV[idx + 1])
+    ARGV.delete_at(idx + 1)
+    ARGV.delete_at(idx)
+  end
+
+  require 'kairos_mcp/skills_config'
+  require 'kairos_mcp/plugin_projector'
+
+  project_root = KairosMcp.project_root
+  projector_mode = KairosMcp.projection_mode
+  projector = KairosMcp::PluginProjector.new(project_root, mode: projector_mode)
+
+  case mode_action
+  when 'project'
+    instructions_mode = KairosMcp::SkillsConfig.load['instructions_mode']
+    if instructions_mode.nil? || instructions_mode == 'none'
+      puts "No active instruction mode (config: instructions_mode = #{instructions_mode.inspect})."
+      puts "Set instructions_mode in #{KairosMcp.skills_config_path} to project a mode body."
+      exit 0
+    end
+
+    body_path = case instructions_mode
+                when 'developer' then KairosMcp.md_path
+                when 'user'      then KairosMcp.quickguide_path
+                when 'tutorial'  then KairosMcp.tutorial_path
+                else File.join(KairosMcp.skills_dir, "#{instructions_mode}.md")
+                end
+
+    unless File.exist?(body_path)
+      warn "ERROR: instruction mode body not found: #{body_path}"
+      exit 1
+    end
+
+    body = File.read(body_path)
+    version = body[/^\*\*Version:\*\*\s*(\S+)/i, 1]
+
+    begin
+      result = projector.project_instruction_mode!(instructions_mode, body, mode_version: version)
+    rescue KairosMcp::PluginProjector::InstructionModeTooLarge => e
+      warn "ERROR: #{e.message}"
+      exit 1
+    end
+
+    puts "Instruction mode projected:"
+    puts "  mode      : #{instructions_mode}#{version ? " v#{version}" : ''}"
+    puts "  source    : #{body_path}"
+    puts "  artifact  : #{result[:artifact_path]}"
+    puts "  size      : #{result[:size_bytes]} bytes"
+    puts "  CLAUDE.md : region #{result[:region_written] ? 'updated' : 'not updated (host file outside project root or unsafe)'}"
+    puts ""
+    puts "Restart Claude Code to apply (CLAUDE.md @-imports resolve at session start)."
+    exit 0
+
+  when 'status'
+    s = projector.instruction_mode_status
+    if s[:active]
+      puts "Instruction mode projection: ACTIVE"
+      puts "  mode      : #{s[:mode_name]}#{s[:mode_version] ? " v#{s[:mode_version]}" : ''}"
+      puts "  artifact  : #{s[:artifact_path]} (#{s[:artifact_size]} bytes)"
+      puts "  region    : #{s[:region_present] ? 'present in CLAUDE.md' : 'absent'}"
+      puts "  projected : #{s[:projected_at]}"
+    else
+      puts "Instruction mode projection: not active for this project."
+    end
+    exit 0
+
+  when 'remove'
+    result = projector.remove_projected_instruction_mode!
+    puts "Instruction mode projection removed:"
+    puts "  artifact  : #{result[:artifact_removed] ? 'deleted' : 'not present'}"
+    puts "  CLAUDE.md : #{result[:region_removed] ? 'region removed' : 'region not present'}"
+    puts ""
+    puts "Restart Claude Code to apply (CLAUDE.md @-imports resolve at session start)."
+    exit 0
+
+  else
+    warn "Unknown mode action: #{mode_action.inspect}"
+    warn "Usage: kairos-chain mode [project|status|remove] [--data-dir DIR]"
+    exit 2
+  end
 end
 
 # Parse CLI options

data/lib/kairos_mcp/plugin_projector.rb

@@ -5,6 +5,7 @@ require 'digest'
 require 'fileutils'
 require 'tempfile'
 require 'time'
+require 'pathname'
 
 module KairosMcp
   # Projects SkillSet plugin artifacts to Claude Code plugin/project structure.
@@ -20,6 +21,12 @@ module KairosMcp
     SAFE_NAME_PATTERN = /\A[a-zA-Z0-9][a-zA-Z0-9_-]*\z/
     ALLOWED_HOOK_COMMANDS = /\Akairos-/
 
+    INSTRUCTION_MODE_MARKER_BEGIN = '<!-- BEGIN kairos-chain:instruction-mode _projected_by=kairos-chain -->'
+    INSTRUCTION_MODE_MARKER_END   = '<!-- END kairos-chain:instruction-mode -->'
+    INSTRUCTION_MODE_REL_PATH     = 'kairos/instruction_mode.md'
+    INSTRUCTION_MODE_SIZE_WARN    = 150 * 1024
+    INSTRUCTION_MODE_SIZE_REFUSE  = 256 * 1024
+
     attr_reader :mode, :project_root, :output_root
 
     def initialize(project_root, mode: :auto)
@@ -27,6 +34,7 @@ module KairosMcp
       @mode = resolve_mode(mode)
       @output_root = @mode == :plugin ? project_root : File.join(project_root, '.claude')
       @manifest_path = File.join(project_root, '.kairos', 'projection_manifest.json')
+      @instruction_mode_manifest_path = File.join(project_root, '.kairos', 'instruction_mode_manifest.json')
     end
 
     # Main entry: project all SkillSet plugin artifacts + L1 knowledge meta skill
@@ -79,6 +87,96 @@ module KairosMcp
       { valid: missing.empty? && orphaned.empty?, missing: missing, orphaned: orphaned }
     end
 
+    # =========================================================================
+    # Instruction mode projection
+    #   See: log/20260507_plugin_projector_instruction_mode_implementation_plan.md
+    #
+    # Materializes the active instruction mode body to a flat file under
+    # <output_root>/<INSTRUCTION_MODE_REL_PATH>, then merges a managed marker
+    # region into project-root CLAUDE.md so the harness picks it up via
+    # `@`-import at session start. State for this artifact is tracked in a
+    # separate manifest (.kairos/instruction_mode_manifest.json) to avoid
+    # mixing symbolic region keys into the main projection manifest.
+    # =========================================================================
+
+    # Project the active instruction mode body.
+    #
+    # @param mode_name [String] active mode name (e.g., 'masa', 'tutorial')
+    # @param body [String] flat mode body (no @-imports inside)
+    # @param mode_version [String, nil] optional version label for the marker header
+    # @return [Hash] result summary { artifact_path:, region_written:, size_bytes: }
+    def project_instruction_mode!(mode_name, body, mode_version: nil)
+      raise ArgumentError, "unsafe mode name: #{mode_name.inspect}" unless safe_name?(mode_name)
+
+      size = body.bytesize
+      raise InstructionModeTooLarge.new(size, INSTRUCTION_MODE_SIZE_REFUSE) if size > INSTRUCTION_MODE_SIZE_REFUSE
+      warn "[PluginProjector] WARNING: instruction mode body is #{size} bytes (warn threshold #{INSTRUCTION_MODE_SIZE_WARN})" if size > INSTRUCTION_MODE_SIZE_WARN
+
+      artifact_path = File.join(@output_root, INSTRUCTION_MODE_REL_PATH)
+      raise "instruction mode artifact path outside output_root: #{artifact_path}" unless safe_path?(artifact_path)
+
+      FileUtils.mkdir_p(File.dirname(artifact_path))
+      atomic_write(artifact_path, body)
+
+      region_written = merge_instruction_mode_region!(mode_name, mode_version, artifact_path)
+
+      save_instruction_mode_manifest(
+        'mode_name' => mode_name,
+        'mode_version' => mode_version,
+        'artifact_path' => artifact_path,
+        'artifact_size' => size,
+        'artifact_digest' => Digest::SHA256.hexdigest(body),
+        'region_present' => region_written,
+        'projected_at' => Time.now.utc.iso8601
+      )
+
+      { artifact_path: artifact_path, region_written: region_written, size_bytes: size }
+    end
+
+    # Remove the projected instruction mode artifact and CLAUDE.md region.
+    #
+    # @return [Hash] result summary { artifact_removed:, region_removed: }
+    def remove_projected_instruction_mode!
+      manifest = load_instruction_mode_manifest
+      artifact_path = manifest['artifact_path'] || File.join(@output_root, INSTRUCTION_MODE_REL_PATH)
+
+      artifact_removed = false
+      if File.exist?(artifact_path) && safe_path?(artifact_path)
+        FileUtils.rm_f(artifact_path)
+        parent = File.dirname(artifact_path)
+        FileUtils.rmdir(parent) if Dir.exist?(parent) && Dir.empty?(parent)
+        artifact_removed = true
+      end
+
+      region_removed = remove_instruction_mode_region!
+
+      save_instruction_mode_manifest(nil) # clear
+
+      { artifact_removed: artifact_removed, region_removed: region_removed }
+    end
+
+    # Status summary for the instruction mode projection.
+    def instruction_mode_status
+      manifest = load_instruction_mode_manifest
+      {
+        mode: @mode,
+        active: !manifest.empty?,
+        mode_name: manifest['mode_name'],
+        mode_version: manifest['mode_version'],
+        artifact_path: manifest['artifact_path'],
+        artifact_size: manifest['artifact_size'],
+        region_present: manifest['region_present'],
+        projected_at: manifest['projected_at']
+      }
+    end
+
+    # Raised when a mode body exceeds the hard refusal threshold.
+    class InstructionModeTooLarge < StandardError
+      def initialize(size, limit)
+        super("instruction mode body too large: #{size} bytes exceeds limit #{limit}")
+      end
+    end
+
     private
 
     def resolve_mode(mode)
@@ -429,5 +527,94 @@ module KairosMcp
         template
       end
     end
+
+    # =========================================================================
+    # Instruction mode helpers (private)
+    # =========================================================================
+
+    # Merge or insert the managed marker region in project-root CLAUDE.md.
+    # Returns true if the region is now present, false otherwise.
+    def merge_instruction_mode_region!(mode_name, mode_version, artifact_path)
+      claudemd = claudemd_path
+      return false unless safe_claudemd_path?(claudemd)
+
+      import_path = relative_import_path(artifact_path)
+      header = "<!-- Active mode: #{mode_name}#{mode_version ? " v#{mode_version}" : ''} | source: .kairos/skills/#{mode_name}.md -->"
+      region = [
+        INSTRUCTION_MODE_MARKER_BEGIN,
+        header,
+        "@#{import_path}",
+        INSTRUCTION_MODE_MARKER_END
+      ].join("\n")
+
+      existing = File.exist?(claudemd) ? File.read(claudemd) : ''
+      stripped = strip_instruction_mode_region(existing)
+      separator = stripped.empty? || stripped.end_with?("\n\n") ? '' : (stripped.end_with?("\n") ? "\n" : "\n\n")
+      new_content = stripped + separator + region + "\n"
+
+      atomic_write(claudemd, new_content)
+      true
+    end
+
+    # Remove the managed marker region from project-root CLAUDE.md if present.
+    # Returns true if a region was removed, false otherwise.
+    def remove_instruction_mode_region!
+      claudemd = claudemd_path
+      return false unless File.exist?(claudemd)
+      return false unless safe_claudemd_path?(claudemd)
+
+      existing = File.read(claudemd)
+      stripped = strip_instruction_mode_region(existing)
+      return false if stripped == existing
+
+      atomic_write(claudemd, stripped)
+      true
+    end
+
+    # Project-root CLAUDE.md absolute path.
+    def claudemd_path
+      File.join(@project_root, 'CLAUDE.md')
+    end
+
+    # Path safety for the host file: must be exactly <project_root>/CLAUDE.md.
+    # Distinct from safe_path? (which gates output_root-confined paths).
+    def safe_claudemd_path?(path)
+      canonical = File.expand_path(path)
+      expected = File.expand_path(claudemd_path)
+      return true if canonical == expected
+      warn "[PluginProjector] WARNING: refusing to mutate non-project CLAUDE.md at '#{path}'"
+      false
+    end
+
+    # Compute the @-import path used inside the marker region.
+    # CLAUDE.md @-imports resolve relative to the project root (where CLAUDE.md lives),
+    # so we emit a project-relative path. The artifact lives under output_root,
+    # which is .claude/ in :project mode.
+    def relative_import_path(artifact_path)
+      Pathname.new(artifact_path).relative_path_from(Pathname.new(@project_root)).to_s
+    end
+
+    # Remove an existing marker region (and any blank-line padding directly
+    # surrounding it) from CLAUDE.md content. Idempotent.
+    def strip_instruction_mode_region(content)
+      pattern = /\n*#{Regexp.escape(INSTRUCTION_MODE_MARKER_BEGIN)}.*?#{Regexp.escape(INSTRUCTION_MODE_MARKER_END)}\n*/m
+      content.sub(pattern, "\n")
+    end
+
+    def load_instruction_mode_manifest
+      return {} unless File.exist?(@instruction_mode_manifest_path)
+      JSON.parse(File.read(@instruction_mode_manifest_path))
+    rescue JSON::ParserError
+      {}
+    end
+
+    def save_instruction_mode_manifest(data)
+      FileUtils.mkdir_p(File.dirname(@instruction_mode_manifest_path))
+      if data.nil?
+        FileUtils.rm_f(@instruction_mode_manifest_path)
+      else
+        atomic_write(@instruction_mode_manifest_path, JSON.pretty_generate(data))
+      end
+    end
   end
 end

data/lib/kairos_mcp/protocol.rb

@@ -159,7 +159,17 @@ module KairosMcp
       KairosMcp.collect_knowledge_entries(user_context: @user_context)
     end
 
-    # Load instructions based on instructions_mode in config.yml
+    # Load instructions based on instructions_mode in config.yml.
+    #
+    # Three states:
+    #   1. Projected (manifest present, region in CLAUDE.md): returns a slim
+    #      identity+pointer payload. Full body reaches the model via CLAUDE.md
+    #      @-import (the privileged delivery path verified in Theme A).
+    #   2. Not yet projected: returns the full body prefixed with a first-run
+    #      hint that tells the LLM how to complete setup (`kairos-chain mode
+    #      project` + restart). Backward-compatible — body still reaches the
+    #      model on this channel, just truncated by the harness as before.
+    #   3. mode == 'none': returns nil.
     #
     # @return [String, nil] Instructions text or nil
     def load_instructions
@@ -181,7 +191,73 @@ module KairosMcp
 
       return nil unless path
 
-      read_if_exists(path)
+      if instruction_mode_projected?(mode)
+        slim_instructions_payload(mode, path)
+      else
+        body = read_if_exists(path)
+        return nil if body.nil?
+        "#{first_run_setup_hint(mode)}\n---\n\n#{body}"
+      end
+    end
+
+    # First-run setup hint prepended to instructions when the instruction
+    # mode body has not yet been projected. Visible to the LLM in the
+    # truncated MCP `instructions` channel; lets the LLM proactively guide
+    # the user through one-time setup without needing prior knowledge.
+    def first_run_setup_hint(mode)
+      <<~HINT.strip
+        # kairos-chain first-run setup notice
+
+        The active instruction mode body ('#{mode}') has NOT been projected to
+        this project's CLAUDE.md yet. The MCP `instructions` channel below is
+        truncated by the Claude Code harness; Agent tool sub-agents do not
+        receive this channel at all.
+
+        To deliver the full mode body to all surfaces (parent + subprocess +
+        sub-agent), run from the project root:
+
+            kairos-chain mode project
+
+        Then restart Claude Code (`exit` then `claude`). After projection,
+        this notice disappears and this MCP channel switches to a slim
+        identity+pointer payload.
+
+        If you (the LLM) detect this notice in your context, surface this
+        setup step to the user with explanation, ask for approval, run the
+        command, and instruct them to restart.
+      HINT
+    end
+
+    # True if the active instruction mode has been projected for this project.
+    def instruction_mode_projected?(mode)
+      manifest_path = File.join(KairosMcp.project_root, '.kairos', 'instruction_mode_manifest.json')
+      return false unless File.exist?(manifest_path)
+      data = JSON.parse(File.read(manifest_path))
+      data['mode_name'] == mode && data['region_present']
+    rescue StandardError
+      false
+    end
+
+    # Identity + pointer payload sent over MCP `instructions` when the body
+    # is delivered via CLAUDE.md @-import. Short enough to clear the harness
+    # truncation cap. Non-Claude-Code consumers retrieve the body from the
+    # registry path directly.
+    def slim_instructions_payload(mode, body_path)
+      version_line = read_if_exists(body_path).to_s[/^\*\*Version:\*\*\s*\S+/i]
+      <<~PAYLOAD
+        # Active instruction mode (delivered via CLAUDE.md @-import)
+
+        - mode_name: #{mode}
+        - #{version_line || 'Version: (none recorded)'}
+        - source_path: #{body_path}
+
+        The full mode body is delivered to the model through this project's
+        CLAUDE.md `@`-import line and is not duplicated here. Non-Claude-Code
+        consumers can retrieve the body from the source_path above.
+
+        Re-run `kairos-chain mode project` after editing the source body
+        and restart Claude Code to apply changes.
+      PAYLOAD
     end
 
     # Read file content if it exists

data/lib/kairos_mcp/version.rb

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

data/templates/knowledge/multi_llm_review_workflow/multi_llm_review_workflow.md

@@ -29,6 +29,103 @@ This skill covers:
 For **WHO** (which LLM is good at what), see: `multi_llm_reviewer_evaluation`
 For **development lifecycle** (design → implement → verify), see: `design_to_implementation_workflow`
 
+## Step 0 — Load reviewer characteristics (mandatory)
+
+**Before invoking any reviewer**, fetch `multi_llm_reviewer_evaluation` via
+`knowledge_get`. That knowledge contains:
+
+- per-reviewer strengths/weaknesses and verdict biases
+- Codex value-system divergence (3 biases) and (a)/(b)/(c) finding classification
+- convergence rule and reviewer-specific signal interpretation
+
+Skipping Step 0 leads to misreading reviewer output — in particular, treating
+Codex (c)-class value-divergent REJECTs as blocking, which causes review loops to
+fail to converge. The cross-reference exists in `related:` frontmatter; this step
+makes it an explicit pre-condition rather than an implicit hint.
+
+## Step 0.5 — Design Direction Block (design / docs reviews only)
+
+For **design-phase** and **knowledge/documentation-update** reviews, prepend a
+**Design Direction Block** to every reviewer prompt, in addition to the project
+philosophy briefing (CLAUDE.md § "Multi-LLM Review Philosophy Briefing"). For
+**implementation-phase** reviews this block is optional — implementation review
+is correctness-vs-design, where philosophy divergence has limited impact.
+
+### Why this exists
+
+Phase 2 Case A (Context Graph review loop, 4 rounds, 2026-05-04) showed that
+a philosophy briefing alone does not shift Codex/Cursor reviewers from REJECT.
+What shifted Cursor to APPROVE in round 4 was **briefing + explicit design
+direction for this artifact**. Codex remained resistant even with both, but the
+(a)/(b)/(c) classification (see `multi_llm_reviewer_evaluation` § Reviewer
+Value-System Divergence) makes its REJECTs digestible. The combination —
+briefing + direction + classification — is the operational protocol that
+prevents review loops from failing to converge over value-system divergence
+mistaken for genuine defects.
+
+### Block structure (prepend to every reviewer prompt)
+
+> **Invariant**: the block declares the artifact's intentional scope so reviewers
+> can distinguish in-scope critique from out-of-scope expectation. The fields below
+> are illustrative facets of that single invariant, not an enumeration of independent
+> requirements; omit fields that do not apply to the artifact rather than forcing
+> content into every slot.
+
+```
+## Design Direction (this artifact)
+
+**Problem this artifact solves**:
+- <one or two sentences>
+
+**Problems this artifact does NOT solve** (out of scope):
+- <bullet: explicitly excluded scope>
+- <bullet: deferred to future design — name the future design if known>
+
+**Rejected alternatives and reasons**:
+- Alt A: <one line> — rejected because <reason>
+- Alt B: <one line> — rejected because <reason>
+
+**Design tradeoffs adopted**:
+- <axis>: chose X over Y because <reason>
+  (e.g., "discipline > infrastructure: workflow-level Step 0 hard fetch
+   over knowledge-graph auto-load, to avoid premature core change")
+- <axis>: chose X over Y because <reason>
+  (e.g., "invariant declaration > mechanism enumeration, per project
+   design-by-invariant principle")
+
+**Where to register additions/objections**:
+- New mechanisms or scope expansions → §11 backlog of the artifact, not body
+- Style/readability concerns not entailed by project principles → (c)
+  value-divergent class, advisory only
+```
+
+### How to author each field
+
+- **Problem solved / not solved**: Should match the artifact's actual scope
+  declarations. If you can't fill these in cleanly, the artifact's scope is
+  unclear — fix that first, then review.
+- **Rejected alternatives**: List at least 2. If you have only 1, you have not
+  considered the design space; design is not yet review-ready.
+- **Tradeoffs**: Name the axis explicitly (X over Y). "We chose X" without an
+  alternative axis is a position, not a tradeoff.
+
+### Effect on reviewer instruction
+
+After the block, instruct reviewers:
+
+> Evaluate against the Design Direction above. Findings inconsistent with the
+> declared scope, rejected alternatives, or tradeoffs are (c) value-divergent
+> by default — record as advisory, not blocking. Findings about the *integrity*
+> of the design (internal contradiction, unrealizable invariant, scope
+> inconsistency) remain (a) deployment-grounded or (b) philosophy-aligned.
+
+### Scope of this step
+
+- Design-phase review: **mandatory**
+- Knowledge / documentation update review: **mandatory** (treated as design)
+- Implementation-phase review: optional — use only when implementation makes
+  significant design choices not fixed by the design artifact
+
 ## Two Execution Paths (read this first)
 
 There are **two distinct execution paths** with the same name "multi-LLM review".

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, and recommended workflows based on 185+ reviews"
-version: "1.2"
+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.3"
 tags:
   - multi-llm
   - review
@@ -21,6 +21,7 @@ Based on 185+ review files across KairosChain development (2026-02-24 to 2026-03
 | Claude Opus 4.6 (Primary) | 15 | 3/18-3/28 | 0% | Designer + reviewer |
 | Claude Team Opus 4.6 | 53 | 3/18-3/28 | 0% | Persona assembly review |
 | Codex GPT-5.4 | 49 | 3/19-3/28 | 27% | Auto review |
+| Codex GPT-5.5 | 4 (Phase 2 Case A) | 2026-05-04 | 100% | Auto review |
 | Cursor Composer-2 | 27 | 3/20-3/28 | 0% | Auto review |
 | Cursor GPT-5.4 | 16 | 3/21-3/25 | 12% | Manual review (Codex fallback) |
 | Cursor Premium | 26 | 3/19-3/21 | 12% | Manual review |
@@ -72,6 +73,14 @@ Based on 185+ review files across KairosChain development (2026-02-24 to 2026-03
 - **Unique findings**: Session Path B authorization re-binding, dead circuit breaker code, plan removal fallback, fail-open content_hash attestation, build_place_client return type mismatch, record_file_usage missing call site
 - **Convergence signal**: Codex APPROVE = high confidence that all issues are genuinely resolved (see Convergence Behavior)
 
+### Codex GPT-5.5
+
+- **Strength**: Same axis as GPT-5.4 (state transition, fail-open detection) plus tighter schema-internal-consistency checks. Round 3 of Phase 2 Case A caught a §5 schema internal contradiction that no Anthropic family or Cursor reviewer caught
+- **Weakness**: Shares all 3 value-system biases with GPT-5.4 (see § Reviewer Value-System Divergence below). Even more resistant to philosophy-briefing internalization than 5.4 in Phase 2 Case A round 4
+- **Pattern**: Treat as "stricter sibling" of GPT-5.4. Same evaluative axis, narrower tolerance
+- **Verdict bias**: REJECT-default; convergence behavior similar to GPT-5.4 but slower
+- **Provisional**: Profile based on Phase 2 Case A 4-round data only. Will refine after additional sessions
+
 ### Cursor Composer-2
 
 - **Strength**: High-level design coherence, protocol correctness, practical deployability, balanced architecture + pragmatics
@@ -115,6 +124,65 @@ Based on 185+ review files across KairosChain development (2026-02-24 to 2026-03
 - **Language**: Japanese-primary (matches project philosophy discussions)
 - **Unique findings**: MerkleTree second preimage attack, Transport Store-and-Forward, challenge expiry penalty automation, `optional` dependency `parsed_depends_on` incompatibility
 
+## Reviewer Value-System Divergence (Phase 2 Case A, 2026-05-04)
+
+This section documents *why* reviewers reject, not *what* they catch. Phase 1 profiles
+(above) record finding categories; Phase 2 Case A revealed that some REJECTs reflect
+the reviewer's own evaluative frame rather than a defect in the artifact. Treating
+those as blocking signals causes review loops to fail to converge (observed: Context
+Graph v1.0-f-high → v1.1 → v1.2, Codex 24/24 REJECT, new P0 every round).
+
+### Codex (GPT-5.4 / 5.5) — 3 structural biases
+
+Both Codex models share these biases against KairosChain's design-by-invariant +
+relational-ontology style. The biases are not bugs in the reviewer; they are a
+different value system that must be classified explicitly.
+
+1. **"Declared behavior must be enforceable."** Industrial-spec-audit frame.
+   Any invariant declared without a verify mechanism is read as documentation drift.
+   Conflicts with KairosChain's relational ontology (no verify, writer responsibility,
+   graceful degradation by design).
+2. **Honest articulation of limits ≡ unresolved spec gap.** §11 backlog entries
+   and ceiling articulations are read as self-reported bugs. The more honest the
+   document, the more Codex rejects — an inversion of the intended discipline.
+3. **"Trust X" + "X is undetectable" = contract contradiction.** A §A "trust X"
+   clause combined with a §B "X cannot be verified" clause is read as a defective
+   contract. Conflicts with the "uncontracted trust = writer responsibility" model.
+
+### Cursor vs Codex briefing reaction (Phase 2 Case A, 4 rounds)
+
+| Round | Briefing | Cursor | Codex 5.4/5.5 |
+|-------|----------|--------|---------------|
+| 1 | none (baseline) | REJECT | REJECT |
+| 2 | philosophy briefing | REJECT | REJECT |
+| 3 | philosophy briefing | REJECT | REJECT |
+| 4 | briefing + design-direction context | **APPROVE** | REJECT (unchanged) |
+
+**Insight**: Cursor internalizes the philosophy briefing once design direction is added;
+Codex is structurally resistant. Briefing-internalization compliance differs by reviewer
+family — track separately when evaluating briefing efficacy.
+
+### (a)/(b)/(c) finding classification
+
+When a reviewer issues a P0, classify the *cause* — not just the severity:
+
+| Class | Definition | Treatment |
+|-------|-----------|-----------|
+| (a) deployment-grounded | Spec violation, runtime bug, data corruption, concurrency hazard. Independent of philosophy. | **Blocking P0** |
+| (b) philosophy-aligned | Deviation from declared design principles (e.g., enumeration where invariant suffices). | **Blocking P0** |
+| (c) value-divergent | Reviewer's own style preference or generic best practice not entailed by project principles. | **Advisory only** (non-blocking) |
+
+When uncertain between (b) and (c), default to (c). Convergence rule applies to (a)+(b);
+(c) findings are recorded but do not block.
+
+**Codex ↔ classes**: Codex finds genuine (a) bugs (e.g., the §5 schema contradiction).
+Codex also produces many (c) findings driven by the 3 biases above. The skill of using
+Codex effectively is **not** silencing it but classifying its output.
+
+> Cross-reference: project CLAUDE.md § "Multi-LLM Review Philosophy Briefing"
+> describes the experimental briefing-prepend protocol that operationalizes this
+> classification. KairosChain_2026 only, experimental.
+
 ## Convergence Behavior (New: 2026-03-28)
 
 ### Codex as Convergence Indicator
@@ -134,17 +202,31 @@ Final Review:    Codex APPROVE | Composer-2 APPROVE+ | Claude APPROVE+
 - When Codex finally APPROVEs, all prior FAIL/HIGH issues have been genuinely resolved
 - **Codex APPROVE = strongest merge-readiness signal** in the 3-LLM configuration
 
-> **Note**: The above convergence data is from the 3-reviewer configuration.
-> With the 4-reviewer default (Opus 4.7 added 2026-04-19), the convergence
-> pattern may shift. Update this section after accumulating 4-reviewer data.
+> **Note**: The above convergence data is from the 3-reviewer configuration in
+> the Attestation Nudge session. With the 4-reviewer default (Opus 4.7 added
+> 2026-04-19), the convergence pattern may shift. Update this section after
+> accumulating 4-reviewer data.
+>
+> **Caveat (Phase 2 Case A, 2026-05-04)**: "Codex APPROVE = strongest signal" is
+> session- and config-dependent. In Phase 2 Case A, Codex never reached APPROVE
+> across 4 rounds even with philosophy briefing + design direction. Treat
+> "waiting for Codex APPROVE" as not always achievable; rely on (a)/(b)/(c)
+> classification (above) rather than verdict-level convergence when value-system
+> divergence dominates.
 
 ### Convergence Rule (Updated)
 
-- 3/4 APPROVE (no REJECT) = proceed to next step (4-reviewer default)
-- Any REJECT or FAIL = revise and re-review
+The convergence rule applies **after** orchestrator classifies findings as (a)/(b)/(c)
+per § Reviewer Value-System Divergence. A REJECT whose findings are entirely (c)
+value-divergent is recorded but treated as non-blocking; only (a)+(b) findings count
+toward the rule below.
+
+- 3/4 APPROVE (no (a)/(b) REJECT) = proceed to next step (4-reviewer default)
+- Any (a) or (b) REJECT or FAIL = revise and re-review
 - **4/4 APPROVE (including Codex) = highest confidence, merge-ready**
 - Legacy 3-reviewer mode: 2/3 APPROVE = proceed
-- Codex-only REJECT + others APPROVE = likely real issue, investigate before overriding
+- Codex-only REJECT with (a)/(b) findings + others APPROVE = likely real issue, investigate before overriding
+- Codex REJECT with only (c) findings = expected per Codex value-system divergence; non-blocking
 
 ### Bug Category Differentiation Across Rounds
 
@@ -157,7 +239,10 @@ Final Review:    Codex APPROVE | Composer-2 APPROVE+ | Claude APPROVE+
 
 **Insight**: Design reviews and implementation reviews find **categorically different bugs**. Design reviews catch "this can't work" (structural). Implementation reviews catch "this doesn't work" (wiring/integration). Both phases are necessary.
 
-## Cost-Benefit (All 7 Models)
+## Cost-Benefit (Phase 1 baseline, 5 reviewers, 2026-02 to 03)
+
+> Baseline only. Opus 4.7 and Codex GPT-5.5 entered the roster post-Phase 1 and are
+> not yet rated here. Refresh after sufficient data accumulates.
 
 | Reviewer | Speed | Security | Impl Quality | Philosophy | Overall ROI |
 |----------|-------|----------|-------------|-----------|-------------|
@@ -204,3 +289,6 @@ Deployment:         Composer-2 or Cursor GPT-5.4
    in the multi-LLM configuration.
 4. Design reviews and implementation reviews find categorically different bugs —
    both phases are necessary for Tier 2+ features.
+5. Some REJECTs reflect the reviewer's value system, not the artifact. The (a)/(b)/(c)
+   classification (see § Reviewer Value-System Divergence) is required to separate
+   blocking signal from advisory noise. Codex models in particular require this lens.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kairos-chain
 version: !ruby/object:Gem::Version
-  version: 3.24.9
+  version: 3.25.0
 platform: ruby
 authors:
 - Masaomi Hatakeyama
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-05 00:00:00.000000000 Z
+date: 2026-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest