kairos-chain 3.90.0 → 3.91.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1f38307df012164fc2070ff3a5a7489f651c678e4bcb75f4d93ef2ba65dec6d
-  data.tar.gz: 11f40f3abe1a502600d451ffb4e6fe757f1cd351fa7f9af7c4c09fe0669f776c
+  metadata.gz: 8edb08c26be7f068db03e377e1f9d48ba67135b233dfa16f0fab9e7126364bca
+  data.tar.gz: 81557a33e8214065bf3e692948b58e3655e0758f5b95e13ae19c9bcc67c4cf17
 SHA512:
-  metadata.gz: 5886c559503ae2223da85857a13e8fa2b365271f5988c3a24b77675ce56215ca481fb581d60f82f523dfe9a1cce4fb81e8b5cfc70f81fb68beec4142183c4450
-  data.tar.gz: de3e9624a91ef9bbc9eaf3712cf64e6367f8b13523c1f3ace774cd31d0c7be4aa5560d60d7f8bfda9197802165dea0ab8a5dd7c74cb2bf666f4c903b26603249
+  metadata.gz: a6fbd7b1e9a1a347f941d292c6b0b55c8801b8ca609503281721d175a7567f27e2b20791ded6b2404eefbc3c6d7d8e84b16f3136fa0faffdad39d3bed574b044
+  data.tar.gz: fcff23454d07a3720ddb982a421137b292e9844228276e445181062ec64ac06025bf4cc4d0afe6c5be4202d889f1b8ddacf10eaa3859cc87ee2d998e627789d4

data/CHANGELOG.md

@@ -4,6 +4,60 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.91.0] - 2026-10-07
+
+### Added — agent: a shadow judge beside the operator (approval delegation, phase 1)
+
+At the points the new delegation table covers, a fresh model answers the
+operator's question beside the operator, and the two answers are compared
+later. **In this phase the judge's answer changes nothing**: every point still
+waits for you.
+
+- **The delegation table** (`lib/agent/delegation_table.yml`) names two
+  points: plan approval in a manual session (`plan_proposed`) and the
+  scheduled checkpoint (`cycle_checkpoint`). Every row is `shadow`; the loader
+  refuses a table with any other mode or with an `mlr` approver. Like the
+  act-route table it is in force only by your terminal ruling, which also pins
+  the instruction mode the judge reads; editing that mode takes the table out
+  of force until you rule again:
+
+      ruby .kairos/skillsets/agent/bin/agent_rule.rb activate --table delegation
+
+  With no ruling, behaviour is as before.
+- **Which points are judged**: only when the act route classifies every step of
+  the plan, no step is marked for a person, nothing touches L0, and the goal is
+  unchanged since the run started. Rows and precedents are chosen only by
+  signals the driver observes from the plan's structure — never by the plan's
+  summary wording or its own risk labels.
+- **The judge** is a separate process (`bin/agent_shadow_judge.rb`) started
+  once the session has stopped at the point; nothing waits for it. It asks
+  `claude-opus-5-5` at effort `xhigh` through `llm_call` (`claude -p`,
+  sandboxed, no fallback provider) with the plan, the driver's signals, the
+  goal, your instruction mode and up to five of your earlier terminal answers
+  at the same kind of stop. Anything but a clear answer from that model counts
+  as "hand back to the operator".
+- **Sealed, then shown**: the verdict goes on the chain as a salted commitment
+  (`agent_shadow_seal`) and is shown only after your answer at that point has
+  committed — in that `agent_step` response and in `agent_status` under
+  `shadow`. Before then `agent_status` says only `judging`, `sealed` or
+  `failed`. The verdict file sits in the session directory; reading it before
+  you answer defeats the comparison.
+- **Counting**: `agent_rule.rb shadow` counts agreement only for answers you
+  typed at the terminal whose seal came first, approve and non-approve apart.
+- Each judged point is one Opus call at `xhigh`.
+
+### Changed — agent: a run with a failed act is not the scheduled checkpoint
+
+An autonomous run now stops as `cycle_checkpoint` only when every act of the
+run succeeded — including an act resumed after a risk pause. A run in which an
+act failed without an act error (a step failed or was denied, the guard failed
+it) stops as `act_failed`, as a failed manual-mode act already did.
+
+### Fixed — agent: a torn read of the chain no longer empties the act-route table
+
+The table loaders retry a read that overlaps a chain append, as the answer
+reader already did.
+
 ## [3.90.0] - 2026-10-07
 
 ### Added — agent: every answer is a ruling on the chain, and an answer typed at a terminal binds

data/lib/kairos_mcp/version.rb

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

data/templates/skillsets/agent/bin/agent_rule.rb

@@ -2,18 +2,23 @@
 # frozen_string_literal: true
 #
 # The operator's terminal rulings for the agent (design v0.3, INV-A2 / INV-D8):
-# the act-route allow-list, and answers at a stopped session.
+# the act-route allow-list, the delegation table, and answers at a stopped
+# session.
 #
 #   ruby .kairos/skillsets/agent/bin/agent_rule.rb activate   # rule the current table into force
 #   ruby .kairos/skillsets/agent/bin/agent_rule.rb withdraw   # take it out of force
 #   ruby .kairos/skillsets/agent/bin/agent_rule.rb status     # show what is in force (records nothing)
 #   ruby .kairos/skillsets/agent/bin/agent_rule.rb answer SESSION_ID
 #                         # answer a stopped session; the MCP answer there must then match
+#   ruby .kairos/skillsets/agent/bin/agent_rule.rb shadow     # count the shadow judge's agreement
+#                                                             # with your answers (records nothing)
 #
-# Options: --data-dir DIR     the instance data dir whose chain is written
+# Options: --table NAME       activate / withdraw: act_classification (default)
+#                             or delegation
+#          --data-dir DIR     the instance data dir whose chain is written
 #                             (default: the .kairos this script is installed in)
-#          --project-dir DIR  answer only: the directory the MCP server runs in,
-#                             whose .kairos/storage holds its agent sessions
+#          --project-dir DIR  answer / shadow: the directory the MCP server runs
+#                             in, whose .kairos/storage holds its agent sessions
 #                             (default: the directory holding the data dir).
 #                             Needed when the server runs with --data-dir
 #                             pointing at another project's .kairos.
@@ -28,11 +33,16 @@
 
 require 'json'
 
-action = ARGV.find { |a| %w[activate withdraw status answer].include?(a) }
-abort 'usage: agent_rule.rb activate|withdraw|status|answer SESSION_ID [--data-dir DIR]' unless action
+action = ARGV.find { |a| %w[activate withdraw status answer shadow].include?(a) }
+abort 'usage: agent_rule.rb activate|withdraw [--table act_classification|delegation]|status|answer SESSION_ID|shadow ' \
+      '[--data-dir DIR] [--project-dir DIR]' unless action
 session_id = action == 'answer' ? ARGV[ARGV.index('answer') + 1].to_s : nil
 abort 'usage: agent_rule.rb answer SESSION_ID [--data-dir DIR]' if session_id&.then { |s| s.empty? || s.start_with?('-') }
 
+tidx = ARGV.index('--table')
+table = tidx ? ARGV[tidx + 1].to_s : 'act_classification'
+abort "--table must be act_classification or delegation, not #{table.inspect}" unless %w[act_classification delegation].include?(table)
+
 idx = ARGV.index('--data-dir')
 data_dir = idx ? File.expand_path(ARGV[idx + 1].to_s) : File.expand_path('../../..', __dir__)
 abort "no data dir at #{data_dir}" unless File.directory?(data_dir)
@@ -50,15 +60,18 @@ lib = File.expand_path('../lib', __dir__)
 require File.join(lib, 'agent', 'admission')
 require File.join(lib, 'agent', 'mandate_adapter')
 require File.join(lib, 'agent', 'act_classification')
+require File.join(lib, 'agent', 'answer_ruling')
+require File.join(lib, 'agent', 'delegation')
+require File.join(lib, 'agent', 'shadow_judge')
 ac = KairosMcp::SkillSets::Agent::ActClassification
+dl = KairosMcp::SkillSets::Agent::Delegation
 path = ac::BASE_PATH
 
 puts "Data dir: #{data_dir}"
-if action == 'answer'
+if %w[answer shadow].include?(action)
   require 'kairos_mcp/invocation_context'
   require File.join(lib, 'agent', 'session')
   require File.join(lib, 'agent', 'advance_gate')
-  require File.join(lib, 'agent', 'answer_ruling')
   # The server keeps agent sessions under <its working directory>/.kairos/storage
   # (Session.storage_path without Autonomos loaded), and its chain under its
   # data dir. The two can differ; the answer is read from the first and
@@ -68,12 +81,14 @@ if action == 'answer'
   project_dir = pidx ? File.expand_path(ARGV[pidx + 1].to_s) : File.dirname(data_dir)
   abort "no project dir at #{project_dir}" unless File.directory?(project_dir)
   Dir.chdir(project_dir)
-  session = KairosMcp::SkillSets::Agent::Session.load(session_id)
-  unless session
-    abort "no agent session #{session_id} under #{File.join(Dir.pwd, '.kairos', 'storage', 'agent_sessions')} " \
-          '(if the MCP server runs in another directory, pass --project-dir)'
-  end
   puts "Sessions from: #{project_dir}"
+  if action == 'answer'
+    session = KairosMcp::SkillSets::Agent::Session.load(session_id)
+    unless session
+      abort "no agent session #{session_id} under #{File.join(Dir.pwd, '.kairos', 'storage', 'agent_sessions')} " \
+            '(if the MCP server runs in another directory, pass --project-dir)'
+    end
+  end
 end
 if action == 'status'
   eff = ac.load_effective(path: path)
@@ -82,6 +97,31 @@ if action == 'status'
   puts "  ruled sha256: #{eff['ruled_sha256'] || '(none)'}"
   puts "  detail: #{eff['detail']}" if eff['detail']
   puts "  tools in force: #{eff['tools'].keys.sort.join(', ')}" unless eff['tools'].empty?
+  deff = dl.load_effective
+  puts "Table #{dl::TABLE_ID}: #{deff['status']}"
+  puts "  file sha256:  #{deff['sha256']}"
+  puts "  detail: #{deff['detail']}" if deff['detail']
+  deff['rows'].each { |r| puts "  row #{r['id']} at #{r['point']} (#{r['mode']})" }
+  deff['reads'].each { |p| puts "  judge reads #{p['name']}: #{p['path']} (sha256 #{p['sha256']})" }
+  exit 0
+end
+if action == 'shadow'
+  ar = KairosMcp::SkillSets::Agent::AnswerRuling
+  sj = KairosMcp::SkillSets::Agent::ShadowJudge
+  records, error = ar.chain_records
+  abort "The chain could not be read (#{error}); nothing to count." if error
+  sessions = File.expand_path(File.join('.kairos', 'storage', 'agent_sessions'))
+  verdict_dir = lambda do |sid, anchor|
+    sid.to_s.match?(/\A[\w-]+\z/) ? sj.anchor_dir(File.join(sessions, sid.to_s), anchor) : File::NULL
+  end
+  sum = sj.agreement(records, verdict_dir: verdict_dir)
+  yes = sum['operator_approved']
+  no = sum['operator_did_not_approve']
+  puts "Pairs that count as evidence (your terminal answer, sealed before it): #{sum['pairs']}"
+  puts "  you approved:          #{yes['n']}; the judge also approved #{yes['judge_agreed']}"
+  puts "  you did not approve:   #{no['n']}; the judge gave the same answer #{no['judge_agreed']}, approved #{no['judge_approved']}"
+  puts "  the judge approved #{sum['judge_approved']} of #{sum['pairs']}"
+  puts "Not counted: #{sum['not_counted'].empty? ? '(none)' : sum['not_counted'].map { |k, v| "#{k} #{v}" }.join(', ')}"
   exit 0
 end
 
@@ -97,6 +137,8 @@ begin
                session: session, gate: KairosMcp::SkillSets::Agent::AdvanceGate.new(session.guard_dir),
                tty_in: tty, tty_out: tty, reload: -> { KairosMcp::SkillSets::Agent::Session.load(session_id) }
              )
+           elsif table == 'delegation'
+             dl.interactive_rule(action: action, tty_in: tty, tty_out: tty)
            else
              ac.interactive_rule(action: action, tty_in: tty, tty_out: tty, path: path)
            end

data/templates/skillsets/agent/bin/agent_shadow_judge.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# The shadow judge's process (design v0.3, INV-D6 / INV-D7). Started detached
+# by the driver after an advance commits, once per anchor, with the packet the
+# driver wrote. It reads the files the packet pins, asks a fresh model the
+# operator's question, writes the verdict beside the packet and appends a
+# salted commitment to it on the chain.
+#
+# It loads no agent tool and never opens the session's advance lock: nothing
+# waits for it, and nothing it does can reach the operator's answer.
+#
+# The model is reached through llm_call (design v0.3 §4), loaded here as a
+# tool object rather than through a registry: provider claude_code (claude -p)
+# with sandbox_mode, the requested model and effort. llm_call falls back to
+# another provider only from a provider other than claude_code, so the judge
+# has none. Its timeout is llm_client's configured one (600 s as shipped).
+#
+# argv: <packet_path>
+# env:  KAIROS_SERVER_LIB  lib dir to load kairos_mcp from
+#       KAIROS_DATA_DIR    the server's data dir (the chain written)
+#       KAIROS_PROJECT_ROOT the server's working directory
+
+require 'json'
+
+packet_path = ARGV[0] or abort 'usage: agent_shadow_judge.rb <packet_path>'
+
+begin
+  Process.setsid
+rescue StandardError
+  # Already a group leader (spawned with pgroup): acceptable.
+end
+
+begin
+  Dir.chdir(ENV['KAIROS_PROJECT_ROOT']) if ENV['KAIROS_PROJECT_ROOT'] && Dir.exist?(ENV['KAIROS_PROJECT_ROOT'])
+  $LOAD_PATH.unshift(ENV['KAIROS_SERVER_LIB']) if ENV['KAIROS_SERVER_LIB']
+  require 'kairos_mcp'
+  KairosMcp.data_dir = ENV['KAIROS_DATA_DIR'] if ENV['KAIROS_DATA_DIR'] && !ENV['KAIROS_DATA_DIR'].empty?
+  require 'kairos_mcp/kairos_chain/chain'
+
+  lib = File.expand_path('../lib', __dir__)
+  require File.join(lib, 'agent', 'answer_ruling')
+  require File.join(lib, 'agent', 'delegation')
+  require File.join(lib, 'agent', 'shadow_judge')
+  require 'kairos_mcp/tools/base_tool'
+  # agent depends on llm_client; both are installed side by side.
+  require File.expand_path('../../llm_client/tools/llm_call', __dir__)
+rescue ScriptError, StandardError => e
+  dir = File.dirname(packet_path)
+  File.write(File.join(dir, 'error.json'),
+             JSON.generate({ 'sealed' => false, 'error' => "bootstrap: #{e.class}: #{e.message[0, 200]}" }))
+  exit 1
+end
+
+llm = lambda do |system:, user:, model:, effort:, provider:|
+  out = KairosMcp::SkillSets::LlmClient::Tools::LlmCall.new(nil).call(
+    'messages' => [{ 'role' => 'user', 'content' => user }], 'system' => system, 'model' => model,
+    'effort' => effort, 'sandbox_mode' => true, 'provider_override' => provider
+  )
+  payload = JSON.parse(Array(out).first[:text])
+  raise "llm_call #{payload.dig('error', 'type')}: #{payload.dig('error', 'message')}" unless payload['status'] == 'ok'
+
+  payload['response'].merge('provider' => payload['provider'])
+end
+
+result = KairosMcp::SkillSets::Agent::ShadowJudge.judge_and_seal(
+  packet_path, llm: llm, chain: KairosMcp::KairosChain::Chain.new
+)
+warn JSON.generate(result)
+exit(result['sealed'] ? 0 : 1)

data/templates/skillsets/agent/lib/agent/act_classification.rb

@@ -92,16 +92,30 @@ module KairosMcp
         end
 
         # [rulings, nil] from the instance chain, or [[], reason] when the
-        # chain cannot be read (which empties the table).
+        # chain cannot be read (which empties the table). The ledger is
+        # rewritten in place on every append, and the shadow judge appends
+        # from its own process at any moment, so a read is retried before a
+        # torn one empties the table (as AnswerRuling.chain_records).
+        READ_ATTEMPTS = 3
+
         def chain_rulings
           return ActClassification.rulings_source.call if ActClassification.rulings_source
 
           require 'kairos_mcp/kairos_chain/chain'
-          chain = ::KairosMcp::KairosChain::Chain.new
-          state = chain.load_state
-          return [[], "chain #{state}"] unless %i[readable absent].include?(state)
-
-          [rulings_from_blocks(chain.chain), nil]
+          reason = nil
+          READ_ATTEMPTS.times do |i|
+            sleep(0.05 * i) if i.positive?
+            begin
+              chain = ::KairosMcp::KairosChain::Chain.new
+              state = chain.load_state
+              return [rulings_from_blocks(chain.chain), nil] if %i[readable absent].include?(state)
+
+              reason = "chain #{state}"
+            rescue StandardError => e
+              reason = "chain unreadable: #{e.class}: #{e.message[0, 120]}"
+            end
+          end
+          [[], reason]
         rescue StandardError, ScriptError => e
           [[], "chain unreadable: #{e.class}: #{e.message[0, 120]}"]
         end

data/templates/skillsets/agent/lib/agent/answer_ruling.rb

@@ -35,6 +35,9 @@ module KairosMcp
       module AnswerRuling
         KIND = 'agent_answer'
         ATTESTATION_KIND = 'agent_answer_attestation'
+        # The shadow judge's sealed verdict at a point (ShadowJudge), read
+        # beside the answers it is counted against.
+        SEAL_KIND = 'agent_shadow_seal'
         TEXTS_FILE = 'answer_texts.jsonl'
 
         # Why a session is waiting. Written with the state change that stops it
@@ -68,14 +71,15 @@ module KairosMcp
           task.nil? ? nil : Digest::SHA256.hexdigest(JSON.generate(task))
         end
 
-        # Answer records in chain order, each with the index of its block.
+        # Answer and seal records in chain order, each with the index of its
+        # block.
         def records_from_blocks(blocks)
           Array(blocks).flat_map do |block|
             data = block.respond_to?(:data) ? block.data : (block['data'] || block[:data])
             index = block.respond_to?(:index) ? block.index : (block['index'] || block[:index])
             Array(data).filter_map do |entry|
               rec = entry.is_a?(String) ? (JSON.parse(entry) rescue nil) : entry
-              next unless rec.is_a?(Hash) && [KIND, ATTESTATION_KIND].include?(rec['kind'])
+              next unless rec.is_a?(Hash) && [KIND, ATTESTATION_KIND, SEAL_KIND].include?(rec['kind'])
 
               rec.merge('block' => index)
             end

data/templates/skillsets/agent/lib/agent/delegation.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+require 'digest'
+require 'time'
+
+module KairosMcp
+  module SkillSets
+    module Agent
+      # The delegation table (design v0.3, INV-A2 / INV-D2 / INV-D3).
+      #
+      # Which approval points a delegate judges beside the operator. Phase 1
+      # has one approver kind (judge) and one mode (shadow), and the loader
+      # refuses a table that names anything else, so with or without a table
+      # every point returns to the operator.
+      #
+      # In force by the rule the classification table follows: the latest
+      # attested agent_table_ruling for table 'delegation' names this file's
+      # sha256. That ruling also pins what the judge reads (judge_reads) by
+      # path and sha256, so the material the judge decides by is material the
+      # operator ruled on (INV-D1); a changed file takes the table out of
+      # force until the operator rules again.
+      module Delegation
+        TABLE_ID = 'delegation'
+        BASE_PATH = File.expand_path('delegation_table.yml', __dir__)
+
+        # The two points a row may name (design v0.3 §1): plan approval in a
+        # manual session, and the scheduled end-of-cycle checkpoint.
+        POINTS = %w[plan_proposed cycle_checkpoint].freeze
+
+        # The driver's signals that it computes from the plan's structure
+        # (steps, tools, location arguments). The other two are the plan's own
+        # claims: design_scope is read from DECIDE's summary, and high_risk
+        # from a risk label the plan may raise (INV-P: declared, never
+        # observed). Rows are matched, and precedents chosen, by these alone,
+        # so the summary's wording and the plan's labels choose neither
+        # (INV-D1). The structure is still the plan's own: a plan can add a
+        # signal (a sixth step, a read under lib/). For rows that only adds to
+        # the floor (INV-D3) — it can keep a point from being judged, never
+        # make one judged; for precedents it selects the rulings that carried
+        # the same signal.
+        OBSERVED_SIGNALS = %w[many_steps l0_change core_files multi_file state_mutation].freeze
+        MATCHABLE_SIGNALS = OBSERVED_SIGNALS
+
+        # What a table may give the judge to read, by symbolic name.
+        READABLE = %w[instruction_mode].freeze
+
+        TOP_KEYS = %w[version judge_reads precedents rows].freeze
+        ROW_KEYS = %w[id point signals_absent approver mode].freeze
+        MAX_PRECEDENTS = 10
+
+        # The judge (design v0.3 §4, operator decision §6.2). No fallback
+        # provider: a judge that cannot be reached as this does not answer.
+        JUDGE = { 'provider' => 'claude_code', 'model' => 'claude-opus-5-5', 'effort' => 'xhigh' }.freeze
+
+        class << self
+          # Test seam: a callable name -> [absolute_path, nil] | [nil, reason].
+          # nil in production (resolve_read).
+          attr_accessor :read_resolver
+        end
+
+        module_function
+
+        # [table, nil] or [nil, error]. table: { 'judge_reads' => [names],
+        # 'precedents_max' => Integer, 'rows' => [row] }.
+        def parse_table(raw)
+          doc = YAML.safe_load(raw)
+          return [nil, 'not a mapping'] unless doc.is_a?(Hash)
+
+          extra = doc.keys.map(&:to_s) - TOP_KEYS
+          return [nil, "unknown keys: #{extra.join(', ')}"] unless extra.empty?
+          return [nil, 'version must be 1'] unless doc.fetch('version', 1) == 1
+
+          reads = doc['judge_reads'] || []
+          return [nil, 'judge_reads must be a list of names'] unless reads.is_a?(Array) && reads.all?(String)
+
+          bad = reads - READABLE
+          return [nil, "judge_reads: #{bad.join(', ')} cannot be read (readable: #{READABLE.join(', ')})"] unless bad.empty?
+
+          prec = doc['precedents'] || {}
+          return [nil, 'precedents must be a mapping with max'] unless prec.is_a?(Hash) && (prec.keys.map(&:to_s) - %w[max]).empty?
+
+          max = prec.fetch('max', 0)
+          unless max.is_a?(Integer) && max.between?(0, MAX_PRECEDENTS)
+            return [nil, "precedents.max must be an integer from 0 to #{MAX_PRECEDENTS}"]
+          end
+
+          rows = doc['rows']
+          return [nil, 'rows must be a list'] unless rows.is_a?(Array)
+
+          ids = []
+          parsed = rows.each_with_index.map do |row, i|
+            label = "row #{i + 1}"
+            return [nil, "#{label}: not a mapping"] unless row.is_a?(Hash)
+
+            extra = row.keys.map(&:to_s) - ROW_KEYS
+            return [nil, "#{label}: unknown keys: #{extra.join(', ')}"] unless extra.empty?
+
+            id = row['id']
+            return [nil, "#{label}: id must be a name such as cycle_checkpoint"] unless id.is_a?(String) && id.match?(/\A[a-z0-9_]+\z/)
+            return [nil, "row #{id}: the id is used twice"] if ids.include?(id)
+
+            ids << id
+            return [nil, "row #{id}: point must be one of #{POINTS.join(', ')}"] unless POINTS.include?(row['point'])
+            if row['approver'] == 'mlr'
+              return [nil, "row #{id}: approver mlr is not available in phase 1 (its verdict is a vote ratio, " \
+                           'which the project has declared non-conclusive)']
+            end
+            return [nil, "row #{id}: approver must be judge"] unless row['approver'] == 'judge'
+            unless row['mode'] == 'shadow'
+              return [nil, "row #{id}: mode #{row['mode'].inspect} is refused; phase 1 runs shadow rows only"]
+            end
+
+            absent = row['signals_absent'] || []
+            return [nil, "row #{id}: signals_absent must be a list"] unless absent.is_a?(Array) && absent.all?(String)
+
+            bad = absent - MATCHABLE_SIGNALS
+            unless bad.empty?
+              return [nil, "row #{id}: signals_absent may name only #{MATCHABLE_SIGNALS.join(', ')} (not #{bad.join(', ')})"]
+            end
+
+            { 'id' => id, 'point' => row['point'], 'signals_absent' => absent, 'approver' => 'judge', 'mode' => 'shadow' }
+          end
+
+          [{ 'judge_reads' => reads, 'precedents_max' => max, 'rows' => parsed }, nil]
+        rescue Psych::Exception => e
+          [nil, "YAML: #{e.message[0, 120]}"]
+        end
+
+        # [absolute_path, nil] or [nil, reason]: the file the server reads for
+        # a readable name. instruction_mode follows the server's own resolution
+        # of the active mode (Protocol#load_instructions).
+        def resolve_read(name)
+          return Delegation.read_resolver.call(name) if Delegation.read_resolver
+          return [nil, "#{name} cannot be read"] unless name == 'instruction_mode'
+
+          require 'kairos_mcp/skills_config'
+          mode = ::KairosMcp::SkillsConfig.load['instructions_mode'] || 'tutorial'
+          path = case mode
+                 when 'developer' then ::KairosMcp.md_path
+                 when 'user' then ::KairosMcp.quickguide_path
+                 when 'tutorial' then ::KairosMcp.tutorial_path
+                 when 'none' then nil
+                 else File.join(::KairosMcp.skills_dir, "#{mode}.md")
+                 end
+          return [nil, 'no instruction mode is active'] unless path
+          return [nil, "#{path} is not readable"] unless File.file?(path)
+
+          [File.expand_path(path), nil]
+        rescue StandardError, ScriptError => e
+          [nil, "#{e.class}: #{e.message[0, 120]}"]
+        end
+
+        # [[{ 'name', 'path', 'bytes', 'sha256' }], nil] or [nil, reason]. One
+        # read per file: the hash is of the bytes counted.
+        def read_pins(names)
+          pins = names.map do |name|
+            path, error = resolve_read(name)
+            return [nil, "#{name}: #{error}"] if error
+
+            raw = File.binread(path)
+            { 'name' => name, 'path' => path, 'bytes' => raw.bytesize, 'sha256' => Digest::SHA256.hexdigest(raw) }
+          end
+          [pins, nil]
+        rescue StandardError => e
+          [nil, "#{e.class}: #{e.message[0, 120]}"]
+        end
+
+        # Names whose path or bytes differ from the ruling's pins, or that one
+        # side has and the other does not.
+        def changed_reads(pins, ruled)
+          ruled = Array(ruled).select { |r| r.is_a?(Hash) }
+          names = (pins.map { |p| p['name'] } + ruled.map { |r| r['name'] }).uniq
+          names.reject do |n|
+            now = pins.find { |p| p['name'] == n }
+            then_ = ruled.find { |r| r['name'] == n }
+            now && then_ && now['path'] == then_['path'] && now['sha256'] == then_['sha256']
+          end
+        end
+
+        # The effective table: { 'status', 'sha256', 'rows', 'judge_reads',
+        # 'precedents_max', 'reads' (pins), 'detail' }. status is 'in_force'
+        # only when every condition holds; otherwise rows is empty.
+        def load_effective(path: BASE_PATH, rulings: nil, rulings_error: nil)
+          ac = ::KairosMcp::SkillSets::Agent::ActClassification
+          rulings, rulings_error = ac.chain_rulings if rulings.nil? && rulings_error.nil?
+          raw = begin
+            File.binread(path)
+          rescue StandardError => e
+            return empty('table_unreadable', nil, detail: "#{e.class}: #{e.message[0, 120]}")
+          end
+          sha = Digest::SHA256.hexdigest(raw)
+          return empty('chain_unreadable', sha, detail: rulings_error) if rulings_error
+
+          latest = Array(rulings).select { |r| r['table'] == TABLE_ID && r['attested'] == true }.last
+          return empty('no_ruling', sha) unless latest
+          return empty('withdrawn', sha) if latest['action'] == 'withdraw'
+          return empty('invalid_ruling', sha) unless latest['action'] == 'activate'
+          return empty('hash_mismatch', sha) unless latest['sha256'] == sha
+
+          table, error = parse_table(raw)
+          return empty('invalid', sha, detail: error) if error
+
+          pins, error = read_pins(table['judge_reads'])
+          return empty('reads_unresolvable', sha, detail: error) if error
+
+          changed = changed_reads(pins, latest['reads'])
+          unless changed.empty?
+            return empty('reads_changed', sha,
+                         detail: "#{changed.join(', ')} changed since the ruling; the judge reads only what was ruled on")
+          end
+
+          table.merge('status' => 'in_force', 'sha256' => sha, 'reads' => pins, 'ruled_at' => latest['ruled_at'])
+        end
+
+        def empty(status, sha, detail: nil)
+          out = { 'status' => status, 'sha256' => sha, 'rows' => [], 'judge_reads' => [], 'precedents_max' => 0,
+                  'reads' => [] }
+          out['detail'] = detail if detail
+          out
+        end
+
+        # The first row, in file order, for this point whose absent signals
+        # are all absent. nil when none matches.
+        def match(effective, point, signals)
+          Array(effective['rows']).find do |row|
+            row['point'] == point && (row['signals_absent'] & Array(signals)).empty?
+          end
+        end
+
+        # ---- the terminal ruling (INV-A2 / INV-D8) ----
+
+        # As ActClassification.interactive_rule, for this table: shows the
+        # rows and what the judge will read, asks for the nonce, and records a
+        # ruling that names the table's sha256 and pins every read.
+        def interactive_rule(action:, tty_in:, tty_out:, path: BASE_PATH, chain: nil,
+                             nonce_value: ::KairosMcp::SkillSets::Agent::ActClassification.nonce)
+          raise ArgumentError, "action must be activate or withdraw, not #{action.inspect}" unless %w[activate withdraw].include?(action)
+
+          sha = nil
+          pins = nil
+          if action == 'activate'
+            raw = File.binread(path)
+            sha = Digest::SHA256.hexdigest(raw)
+            table, error = parse_table(raw)
+            pins, error = read_pins(table['judge_reads']) unless error
+            if error
+              tty_out.puts "Refused: #{path} cannot be ruled into force (#{error})."
+              return { 'recorded' => false, 'reason' => 'invalid', 'detail' => error }
+            end
+            tty_out.puts "Table:  #{TABLE_ID}"
+            tty_out.puts "File:   #{path}"
+            tty_out.puts "sha256: #{sha}"
+            tty_out.puts "Phase 1: every row is shadow. A judge (#{JUDGE['model']}, effort #{JUDGE['effort']}, " \
+                         "through #{JUDGE['provider']}) answers beside you at these points; its verdict is sealed " \
+                         'before your answer, shown after it, and changes nothing.'
+            table['rows'].each do |row|
+              absent = row['signals_absent'].empty? ? '' : " unless the driver sees #{row['signals_absent'].join(', ')}"
+              tty_out.puts "  #{row['id'].ljust(22)} at #{row['point']}#{absent}"
+            end
+            tty_out.puts 'The judge reads (pinned by this ruling; a change takes the table out of force):'
+            pins.each { |p| tty_out.puts "  #{p['name']}: #{p['path']} (#{p['bytes']} bytes, sha256 #{p['sha256']})" }
+            tty_out.puts "and up to #{table['precedents_max']} of your earlier terminal answers at the same stop " \
+                         'with the same signals.'
+          else
+            tty_out.puts "Withdraw table #{TABLE_ID}: no judge runs until a new ruling."
+          end
+          tty_out.puts
+          tty_out.print "Type #{nonce_value} to record this ruling (anything else cancels): "
+          tty_out.flush
+          unless tty_in.gets.to_s.strip == nonce_value
+            tty_out.puts 'Cancelled. Nothing was recorded.'
+            return { 'recorded' => false, 'reason' => 'nonce_mismatch' }
+          end
+
+          record = { 'kind' => ::KairosMcp::SkillSets::Agent::ActClassification::RULING_KIND, 'table' => TABLE_ID,
+                     'action' => action, 'sha256' => sha, 'attested' => true, 'attestation' => 'terminal_nonce',
+                     'ruled_at' => Time.now.utc.iso8601 }
+          record['reads'] = pins.map { |p| p.slice('name', 'path', 'sha256') } if pins
+          chain ||= begin
+            require 'kairos_mcp/kairos_chain/chain'
+            ::KairosMcp::KairosChain::Chain.new
+          end
+          block = chain.add_block([JSON.generate(record)])
+          tty_out.puts "Recorded as block ##{block.index}."
+          { 'recorded' => true, 'block_index' => block.index, 'record' => record }
+        end
+      end
+    end
+  end
+end