kairos-chain 3.67.0 → 3.68.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0506a7cc642b812cabab1bb2840d928e1a9f550bf2486466741a54b6d71ee74f
-  data.tar.gz: bf1ff56bf44cf13d78c01dedd26d0bdc6188453dea18ca1975027f2b3a6c7f8d
+  metadata.gz: 7ac682d1d3fc16af582fb7eadccc08c263b9a2161805de89859e0c0d036c694a
+  data.tar.gz: 5d5ebdcac2a80196a1ed4bdd322b69b5de9a027c23f384d315ab7ab5a5119e5f
 SHA512:
-  metadata.gz: 7c4ef69fda47be727f4ba9da5f44ee95d6cf63f5cff559bb3b3b2cc7dfc8df67022f47086d6468b6dc332f41b95908745557e294d2bc8d1e4dec70a763ec208a
-  data.tar.gz: 1838ad363f5bc95a8e5abdb1ca07c7be7891a0ab5410cbdc22456b5187bc4297f193d57f2a93b57578582704702b788eb2e5e78d5c4ff7c0f978bcc58c8cd4c5
+  metadata.gz: 12b7c204a2e70e581d6746452e5faa64c991c8f07536d1531f3aebbae45dadcd783ccd75a736bd00bacecf92ffb00cd5dbb6cb1cba285fb8447d82c9899ca1d1
+  data.tar.gz: 63188706bfebce9144966aa795f26b875102ac66696e89100fd90e3b5fbca09705910a790cb0bf284dc20270a290e7a413cf7cb32413ec09fb55f2183f0ef991

data/bin/kairos-chain

@@ -406,6 +406,122 @@ when 'upgrade'
   end
   exit
 
+when 'gate'
+  # Readable-gate enablement in one call. The judgement lives in the
+  # kairos_hook_projector SkillSet, which is not a core SkillSet: this loads it
+  # from the instance and refuses when it is absent, the shape `attestation
+  # scan` already uses for synoptis. Loading it from the gem's templates instead
+  # would run a different copy than the one installed here.
+  ARGV.shift
+
+  action = ARGV.shift
+  if action.nil? || %w[-h --help help].include?(action)
+    puts <<~HELP
+      Usage: kairos-chain gate enable <mode> [--section "§ Heading"] [--apply]
+
+      Add the readable gate to an instruction mode: write the declaration
+      from the catalogue, then install it into .claude/settings.json.
+
+      Without --apply it proposes and writes nothing.
+
+      It does not read the mode body and decides nothing about it. The
+      section and the thresholds come from the catalogue and are the mode's
+      own to edit afterwards, in the declaration this prints. `blocking`
+      starts false, which is what the catalogue ships: run report-only,
+      read the log, then set it true and re-run with --apply.
+
+      A verdict of OPEN_QUESTIONS after a successful install is not a
+      failure — it means some other section of the mode states a limit with
+      no recorded decision. Record it under not_gated in the declaration.
+
+      Options:
+        --section "§ Heading"  Write this section instead of the catalogue's.
+        --apply                Write. Default is propose-only.
+        --data-dir DIR         Override the .kairos/ data directory.
+
+      Requires: kairos-chain skillset install kairos_hook_projector
+    HELP
+    exit 0
+  end
+
+  $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+  require 'json'
+  require 'kairos_mcp'
+
+  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
+
+  unless action == 'enable'
+    warn "ERROR: unknown action #{action.inspect}. See: kairos-chain gate --help"
+    exit 1
+  end
+
+  gate_apply = !ARGV.delete('--apply').nil?
+  gate_section = nil
+  if (idx = ARGV.index('--section'))
+    gate_section = ARGV[idx + 1]
+    if gate_section.nil? || gate_section.start_with?('--')
+      warn 'ERROR: --section requires a heading, e.g. --section "§ Readable output"'
+      exit 1
+    end
+    ARGV.delete_at(idx + 1)
+    ARGV.delete_at(idx)
+  end
+
+  gate_mode = ARGV.find { |a| !a.start_with?('--') }
+  if gate_mode.nil?
+    warn 'ERROR: name the mode. Omitting it would target the active mode, which'
+    warn '       on a stock init is tutorial — a shipped body with nothing to gate.'
+    warn '       Usage: kairos-chain gate enable <mode> [--apply]'
+    exit 1
+  end
+
+  ss_root = File.join(KairosMcp.skillsets_dir, 'kairos_hook_projector')
+  unless File.directory?(File.join(ss_root, 'tools'))
+    warn 'ERROR: kairos_hook_projector is not installed on this instance.'
+    warn '       kairos-chain skillset install kairos_hook_projector'
+    exit 1
+  end
+
+  require 'kairos_mcp/tools/base_tool'
+  require 'kairos_mcp/kairos_chain/chain'
+  require File.join(ss_root, 'lib', 'readable_gate_setup')
+
+  result = KairosMcp::SkillSets::KairosHookProjector::ReadableGateSetup
+           .new(skillset_root: ss_root).run(mode: gate_mode, section: gate_section,
+                                            apply: gate_apply)
+
+  case result.status
+  when :refused
+    warn "REFUSED: #{result.detail}"
+    exit 1
+  when :proposed
+    puts JSON.pretty_generate(result.data['plan'])
+    puts
+    puts "declaration: #{result.data['declaration']}"
+    puts 'Nothing written. Re-run with --apply to install.'
+    exit 0
+  else
+    installed = result.data.dig('checks', 'installed') || {}
+    declared = result.data.dig('checks', 'declared') || {}
+    puts "verdict    : #{result.data['verdict']}"
+    puts "installed  : #{installed['status']} — #{installed['detail']}"
+    puts "declaration: #{result.data['declaration']}"
+    puts
+    puts 'Installed, and reporting only — blocking is false, as the catalogue ships it.'
+    # Reported, not treated as failure: the gate is on either way.
+    if result.data['verdict'] == 'OPEN_QUESTIONS'
+      puts
+      puts "Also: #{declared['detail']}"
+      puts "Sections: #{Array(declared['candidate_sections']).join(', ')}"
+      puts 'Record a decision for each under not_gated in the declaration, or gate them.'
+    end
+    exit 0
+  end
+
 when 'attestation'
   # Constitutive L2 attestation CLI (Slice 3c). Currently one action: `scan`, the
   # ACT-5 trigger point invokable from a session-end Stop hook so that firing +

data/lib/kairos_mcp/version.rb

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

data/templates/skillsets/kairos_hook_projector/lib/readable_gate_setup.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module KairosMcp
+  module SkillSets
+    module KairosHookProjector
+      # Add the readable gate to a mode, in one call: declare it, then install
+      # it. Nothing else.
+      #
+      # It does not read the mode body and it decides nothing about it. An
+      # earlier draft derived `section` from the validator's candidate list and
+      # refused when that list was not exactly one entry — which put a reading
+      # of the mode inside a command whose job is to add a gate, and turned
+      # `tutorial` into an interrogation. The declaration is written from the
+      # catalogue, section and thresholds included; they are the mode's own to
+      # edit afterwards, in the file this points at.
+      #
+      # `blocking` stays false, because that is what the catalogue ships. The
+      # verdict is reported as the validator states it — including
+      # OPEN_QUESTIONS, which means the gate is installed and some other
+      # section of the mode carries a limit with no recorded decision. That is
+      # information, not failure, and the same draft reported it as a refusal
+      # after a successful install.
+      class ReadableGateSetup
+        # status: :ok | :proposed | :refused
+        Result = Struct.new(:status, :detail, :data, keyword_init: true)
+
+        GATE = 'readable_gate'
+
+        # `tools` exists so the sequence and the status mapping can be driven
+        # with doubles, the way this SkillSet's other tests drive the tools
+        # themselves. Default is the real trio; nothing else supplies it.
+        def initialize(skillset_root:, tools: nil)
+          @root = skillset_root
+          @tools = tools
+        end
+
+        def run(mode:, section: nil, apply: false)
+          load_tools
+
+          added = call(tool(:add), 'mode' => mode, 'gate' => GATE)
+          declaration = added['declaration']
+          unless declaration && %w[created appended].include?(added['action'])
+            return refuse('mode_hooks_add wrote no declaration: ' \
+                          "#{added['refusal'] || added['error'] || added['action'] || added.inspect}")
+          end
+          rename_section(declaration, section) if section
+
+          plan = call(tool(:project), 'mode' => mode)
+          if plan['plan_sha256'].nil?
+            return refuse("mode_hooks_project refused: #{plan['detail'] || plan.inspect}")
+          end
+
+          data = { 'declaration' => declaration, 'plan' => plan }
+          return Result.new(status: :proposed, detail: 'nothing written', data: data) unless apply
+
+          applied = call(tool(:project), 'mode' => mode, 'apply' => true,
+                                         'confirm_sha256' => plan['plan_sha256'])
+          unless applied['action'] == 'applied'
+            return refuse("apply did not apply: #{applied['action'] || applied.inspect}")
+          end
+
+          # The apply result asserts no liveness in either direction, by design.
+          # A fresh read is the only thing that answers whether the gate is on.
+          after = call(tool(:validate), 'mode' => mode)
+          Result.new(status: :ok, detail: 'installed',
+                     data: data.merge('verdict' => after['verdict'],
+                                      'checks' => after['checks']))
+        end
+
+        private
+
+        def refuse(detail)
+          Result.new(status: :refused, detail: detail, data: nil)
+        end
+
+        # mode_hooks_add takes no `section`, so a caller who named one has it
+        # written here, into the file add just wrote. No check that the heading
+        # exists: the caller said it, and the mode body is theirs.
+        def rename_section(path, section)
+          doc = JSON.parse(File.read(path, encoding: 'UTF-8'))
+          entry = doc.dig('hooks', 'Stop')&.find { |e| e['gate'] == GATE }
+          return if entry.nil?
+
+          entry['section'] = section
+          File.write(path, JSON.pretty_generate(doc) + "\n", encoding: 'UTF-8')
+        end
+
+        def call(klass, args)
+          JSON.parse(klass.new.call(args).first[:text])
+        end
+
+        def tool(which)
+          return @tools.fetch(which) if @tools
+
+          { add: Tools::ModeHooksAdd, project: Tools::ModeHooksProject,
+            validate: Tools::ModeHooksValidate }.fetch(which)
+        end
+
+        def load_tools
+          return if @tools || (defined?(@loaded) && @loaded)
+
+          %w[mode_hooks_add mode_hooks_project mode_hooks_validate].each do |t|
+            require File.join(@root, 'tools', t)
+          end
+          @loaded = true
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/kairos_hook_projector/test/test_readable_gate_setup.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require 'json'
+require 'tmpdir'
+
+require_relative '../lib/readable_gate_setup'
+
+# The one-call path: declare, then install. What is worth witnessing here is
+# not the tools — they have their own suites — but the sequence and the status
+# this reports for each answer they can give. The first draft of this class got
+# the last one wrong in the shape this whole SkillSet exists to prevent: it
+# reported a successful install as a refusal.
+class TestReadableGateSetup < Minitest::Test
+  S = KairosMcp::SkillSets::KairosHookProjector::ReadableGateSetup
+
+  # A double per tool, returning canned bodies in the tools' real shape.
+  class FakeTool
+    class << self
+      attr_accessor :replies, :calls
+    end
+
+    def call(args)
+      self.class.calls ||= []
+      self.class.calls << args
+      body = self.class.replies.shift
+      [{ type: 'text', text: JSON.generate(body) }]
+    end
+  end
+
+  def tool_class(*replies)
+    Class.new(FakeTool).tap { |k| k.replies = replies.dup }
+  end
+
+  def setup
+    @dir = Dir.mktmpdir
+    @decl = File.join(@dir, 'demo.mode_hooks.json')
+    File.write(@decl, JSON.generate(
+                        'mode_name' => 'demo', 'version' => '1',
+                        'hooks' => { 'Stop' => [{ 'gate' => 'readable_gate',
+                                                  'section' => '§ Readable output' }] }
+                      ))
+  end
+
+  def added(action = 'created')
+    { 'action' => action, 'declaration' => @decl }
+  end
+
+  def run_with(add:, project:, validate: nil, **kwargs)
+    S.new(skillset_root: @dir,
+          tools: { add: add, project: project, validate: validate })
+     .run(**{ mode: 'demo' }.merge(kwargs))
+  end
+
+  def test_a_declared_gate_is_installed_and_the_validators_verdict_is_carried_out
+    project = tool_class({ 'plan_sha256' => 'abc' }, { 'action' => 'applied' })
+    out = run_with(add: tool_class(added), project: project,
+                   validate: tool_class('verdict' => 'OK',
+                                        'checks' => { 'installed' => { 'status' => 'ok' } }),
+                   apply: true)
+    assert_equal :ok, out.status
+    assert_equal 'OK', out.data['verdict']
+    assert_equal @decl, out.data['declaration']
+
+    # The apply must echo the digest the proposal returned; a fresh digest, or
+    # none, is refused by the tool and nothing would be written.
+    assert_equal 'abc', project.calls.last['confirm_sha256']
+    assert_equal true, project.calls.last['apply']
+  end
+
+  # The defect this file exists for. OPEN_QUESTIONS means the gate IS installed
+  # and some other section of the mode states a limit with no recorded
+  # decision. Reporting that as a refusal told the operator their install had
+  # failed when it had not — the same false sentence about a live gate that
+  # round 16 removed from the validator.
+  def test_open_questions_after_a_successful_install_is_reported_not_refused
+    out = run_with(add: tool_class(added),
+                   project: tool_class({ 'plan_sha256' => 'abc' }, { 'action' => 'applied' }),
+                   validate: tool_class('verdict' => 'OPEN_QUESTIONS',
+                                        'checks' => { 'installed' => { 'status' => 'ok' },
+                                                      'declared' => { 'status' => 'open' } }),
+                   apply: true)
+    assert_equal :ok, out.status,
+                 'the gate is installed; an unrecorded decision elsewhere is not a failure'
+    assert_equal 'OPEN_QUESTIONS', out.data['verdict'], 'and the verdict is not swallowed'
+    assert_equal 'ok', out.data.dig('checks', 'installed', 'status')
+  end
+
+  def test_without_apply_it_proposes_and_the_project_tool_is_called_once
+    project = tool_class('plan_sha256' => 'abc')
+    out = run_with(add: tool_class(added), project: project)
+    assert_equal :proposed, out.status
+    assert_equal 1, project.calls.length, 'a proposal must not be followed by an apply'
+    refute project.calls.first.key?('apply')
+  end
+
+  def test_a_refused_declaration_stops_before_the_projector_runs
+    project = tool_class('plan_sha256' => 'abc')
+    out = run_with(add: tool_class('action' => 'refused', 'refusal' => 'unknown_gate'),
+                   project: project, apply: true)
+    assert_equal :refused, out.status
+    assert_match(/unknown_gate/, out.detail)
+    assert_nil project.calls, 'nothing may be projected from a declaration that was not written'
+  end
+
+  # An apply that answers anything other than `applied` has not written. Taking
+  # the call's return as evidence of the write is how this SkillSet's stage 2
+  # went a whole round having never written a file.
+  def test_an_apply_that_did_not_apply_is_refused_and_no_verdict_is_invented
+    validate = tool_class('verdict' => 'OK')
+    out = run_with(add: tool_class(added),
+                   project: tool_class({ 'plan_sha256' => 'abc' },
+                                       { 'action' => 'refused_confirmation' }),
+                   validate: validate, apply: true)
+    assert_equal :refused, out.status
+    assert_match(/refused_confirmation/, out.detail)
+    assert_nil validate.calls, 'a validate answer must not be reported for a write that did not happen'
+  end
+
+  def test_a_named_section_replaces_the_catalogues_and_nothing_else_moves
+    run_with(add: tool_class(added),
+             project: tool_class('plan_sha256' => 'abc'),
+             section: '§ 形')
+    doc = JSON.parse(File.read(@decl, encoding: 'UTF-8'))
+    assert_equal '§ 形', doc.dig('hooks', 'Stop', 0, 'section')
+    assert_equal 'readable_gate', doc.dig('hooks', 'Stop', 0, 'gate')
+    assert_equal 'demo', doc['mode_name']
+  end
+
+  def test_without_a_section_the_catalogues_value_is_left_alone
+    run_with(add: tool_class(added), project: tool_class('plan_sha256' => 'abc'))
+    doc = JSON.parse(File.read(@decl, encoding: 'UTF-8'))
+    assert_equal '§ Readable output', doc.dig('hooks', 'Stop', 0, 'section'),
+                 'this command reads no mode body and must not decide the section'
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kairos-chain
 version: !ruby/object:Gem::Version
-  version: 3.67.0
+  version: 3.68.0
 platform: ruby
 authors:
 - Masaomi Hatakeyama
@@ -594,6 +594,7 @@ files:
 - templates/skillsets/kairos_hook_projector/lib/mode_hooks_compiler.rb
 - templates/skillsets/kairos_hook_projector/lib/mode_hooks_locator.rb
 - templates/skillsets/kairos_hook_projector/lib/mode_hooks_schema.rb
+- templates/skillsets/kairos_hook_projector/lib/readable_gate_setup.rb
 - templates/skillsets/kairos_hook_projector/mode_hooks/_EXAMPLE.json
 - templates/skillsets/kairos_hook_projector/mode_hooks/_record_schema.json
 - templates/skillsets/kairos_hook_projector/mode_hooks/_schema.json
@@ -608,6 +609,7 @@ files:
 - templates/skillsets/kairos_hook_projector/test/test_mode_hooks_schema.rb
 - templates/skillsets/kairos_hook_projector/test/test_mode_hooks_validate.rb
 - templates/skillsets/kairos_hook_projector/test/test_readable_gate.rb
+- templates/skillsets/kairos_hook_projector/test/test_readable_gate_setup.rb
 - templates/skillsets/kairos_hook_projector/test/test_skillset_json.rb
 - templates/skillsets/kairos_hook_projector/tools/hooks_status.rb
 - templates/skillsets/kairos_hook_projector/tools/mode_hooks_add.rb