kairos-chain 3.65.0 → 3.66.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b5f8504e1a59fe2e58603f654ad32a747381897a62dba70ba436388c5be3f55
-  data.tar.gz: c4c86ca90fb56858a45c126aca497277846225c1b127549700be1e80484c0755
+  metadata.gz: b16a89f65901c9eefc5b08e5c2b1503817625c35847304332316ddb01292f8da
+  data.tar.gz: 7724c71a90c96aa624003663b4e7a7381552a08d0afa857ca19969fdea997875
 SHA512:
-  metadata.gz: 3535630f908f30fc87319e960207ea5552de1f29284211cf24e4802171a7699b3ebcde4ebce74875341d368004ea04ccf36211f4b68037755907a1ef77550ae6
-  data.tar.gz: a01fbf7861eac890a2d020ce8a0606970d41a7a9f3d0f1840f1db7a19580c87f77b77af1ffebd4028c538f4535b562db78adff1c847389c2fd6a162dda5fa3f4
+  metadata.gz: 3dc1c2f28e0b5b515f89be1bf7eb6714c796deae4ab8382907b0248abcabefc74e2510c372c3a3fc18eb2b8c7d36accd58535d2b9528398b83e6d2b2618e3a8b
+  data.tar.gz: 5d33acb30a5c7510015d76c7d9d398597988e284e5420752385888e0814b19ba6332528cb701e925e82fb414f7c08bc3a3930ee990065070756701bcd07dc4ee

data/lib/kairos_mcp/version.rb

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

data/templates/skillsets/kairos_hook_projector/mode_hooks/_EXAMPLE.json

@@ -50,6 +50,7 @@
     "Stop": [
       {
         "gate": "readable_gate",
+        "_description": "Measures the turn's last message against declared readability limits — length, headings, tables, undefined shorthand, a missing diagram — and reports to its log, or blocks the turn once blocking is true.",
         "section": "§ Readable output",
 
         "_blocking_note": "false on purpose in the example. The vocabulary rule below is the one thing here that cannot be got right by reading: whether a shape is coined shorthand or an ordinary technical word depends on what you write about. Start in report-only mode, read your log for a week, then set this to true. Shipping the example with true meant a consumer who copied it as instructed was blocked on the first message mentioning a character encoding.",

data/templates/skillsets/kairos_hook_projector/plugin/SKILL.md

@@ -20,16 +20,42 @@ under `.kairos/hook_configs/`.
 Not auto-installed (not a core SkillSet): install it by name first —
 `system_upgrade command="apply" approved=true names=["kairos_hook_projector"]`.
 
-1. Copy `mode_hooks/_EXAMPLE.json` beside your mode body as
-   `<mode>.mode_hooks.json` (e.g. `.kairos/skills/masa.mode_hooks.json`).
-2. Edit `mode_name` inside it to `<mode>` — filename and field must agree —
-   and replace the example numbers with your own.
-3. `mode_hooks_validate` reports what the copy still needs.
+1. `mode_hooks_add mode="<mode>" gate="readable_gate"` writes
+   `<mode>.mode_hooks.json` beside the mode body — creating it, or appending
+   to it; an entry with the same gate already on the event is refused, never
+   overwritten. Omitting `mode` targets the active mode, and on a stock init
+   that is `tutorial` — a gem-shipped template body carrying no
+   readable-output norm — so name your mode. The entry comes from the
+   catalogue (`mode_hooks/_EXAMPLE.json`): event, section, blocking, and
+   starting params. Tune the numbers in the written file afterwards, they are
+   the mode's own — and edit `section` to a heading your mode body actually
+   contains: it is copied from the catalogue, it is a claim about your own
+   text, and the gate quotes it verbatim in every block reason. Called
+   without `gate` it lists the catalogue and writes nothing. It stops at the
+   declaration and never touches `.claude/settings.json`.
+2. Or by hand, for someone who wants to write the numbers themselves: copy
+   `mode_hooks/_EXAMPLE.json` beside your mode body as
+   `<mode>.mode_hooks.json` (e.g. `.kairos/skills/masa.mode_hooks.json`),
+   then edit `mode_name` inside it to `<mode>` — filename and field must
+   agree — edit `section` to a heading your mode body actually contains (the
+   gate quotes it verbatim in every block reason), and replace the example
+   numbers with your own.
+3. `mode_hooks_validate` reports what the declaration still needs.
 4. `mode_hooks_project` proposes by default and writes nothing; to install,
    call again with `apply=true` and the `confirm_sha256` from the proposal.
 5. `mode_hooks_validate`, run again, answers whether the gate is installed:
    its `installed` check compares declaration and `.claude/settings.json`.
 
+The catalogue is gem-shipped and is not an extension point on the instance:
+`system_upgrade` overwrites `mode_hooks/_EXAMPLE.json` on any reinstall — at
+the same version, with no warning, without naming the file — so an edit to
+the installed copy does not survive. Adding a gate kind is a core release
+act: the catalogue entry, the kind in the compiler's known-gate table (until
+then every call refuses it as `unknown_gate`), and the gate implementation
+itself. Your declaration lives beside the mode body, outside the SkillSet,
+for the same reason — the tool refuses to write declarations inside the
+SkillSet directory because an upgrade would undo them.
+
 ## Removing a mode's hooks
 
 Two routes, and either works: empty the declaration's `hooks` object
@@ -54,6 +80,9 @@ installed command names them; delete them by hand if you want them gone.
 
 ## Tools
 
+- `mode_hooks_add` — write or extend a mode's declaration from the catalogue
+  (`mode_hooks/_EXAMPLE.json`); append-only, stops at the declaration, never
+  touches `.claude/settings.json`. Without `gate`, lists the catalogue.
 - `mode_hooks_validate` (read-only) — mode body vs declaration drift, compile
   resolvability, and declared-vs-installed divergence in both directions.
 - `mode_hooks_project` — compile and install; touches only entries it placed

data/templates/skillsets/kairos_hook_projector/skillset.json

@@ -1,6 +1,6 @@
 {
   "name": "kairos_hook_projector",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Projects an instruction mode's declared hooks into the harness configuration. Stage 1 compiles a mode_hooks declaration to a hook artifact plus a compile record. Stage 2 installs it: mode_hooks_project proposes by default and writes nothing, applying only when the caller echoes back the artifact hash from the proposal, and rewriting only hook groups carrying this SkillSet's marker for that mode — hand-added hooks and other modes' hooks are counted and left alone. Ships the generic readable_gate implementation; a mode supplies its own thresholds, the core supplies none.",
   "author": "Masaomi Hatakeyama",
   "layer": "L1",
@@ -15,12 +15,14 @@
     "hooks_status_readonly",
     "mode_hooks_validation",
     "mode_hooks_projection",
+    "mode_hooks_declaration",
     "readable_gate"
   ],
   "tool_classes": [
     "KairosMcp::SkillSets::KairosHookProjector::Tools::HooksStatus",
     "KairosMcp::SkillSets::KairosHookProjector::Tools::ModeHooksValidate",
-    "KairosMcp::SkillSets::KairosHookProjector::Tools::ModeHooksProject"
+    "KairosMcp::SkillSets::KairosHookProjector::Tools::ModeHooksProject",
+    "KairosMcp::SkillSets::KairosHookProjector::Tools::ModeHooksAdd"
   ],
   "config_files": [],
   "knowledge_dirs": [],

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

@@ -0,0 +1,541 @@
+# frozen_string_literal: true
+
+require 'minitest/autorun'
+require 'json'
+require 'tmpdir'
+require 'fileutils'
+require 'digest'
+
+# Guarded, and it has to be. Three test files defined this stub unconditionally
+# and reopened the class, so whichever loaded last decided the return shape for
+# everybody. Loading all the files together made test_hooks_status fail — a
+# failure invisible to a per-file run.
+module KairosMcp
+  module Tools
+    class BaseTool
+      def initialize(safety = nil, registry: nil); end
+
+      def text_content(text)
+        [{ type: 'text', text: text }]
+      end
+    end
+  end
+end unless defined?(::KairosMcp::Tools::BaseTool)
+
+require_relative '../tools/mode_hooks_add'
+require_relative '../lib/mode_hooks_compiler'
+
+class TestModeHooksAdd < Minitest::Test
+  SKILLSET_ROOT = File.expand_path('..', __dir__)
+  COMPILER = KairosMcp::SkillSets::KairosHookProjector::ModeHooksCompiler
+
+  # A real mode body is Japanese with § headings. The read feeds the binding
+  # digest and the compile, and the section below lands verbatim in the
+  # declaration this tool rewrites on append — so these bytes make the reads
+  # and writes fail under a US-ASCII default locale if any encoding argument
+  # is dropped.
+  BODY = "**Version:** 0.1.0\n## § 形\n応答は 60 行以内。長くなるなら図を一枚。\n"
+
+  # Test double: the environment lookups are the impure surface. Catalogue,
+  # locator, compiler and the write are the real thing.
+  class Adder < KairosMcp::SkillSets::KairosHookProjector::Tools::ModeHooksAdd
+    attr_accessor :root, :catalogue_override, :skillset_root_override
+
+    private
+
+    def resolve_project_root = @root
+    def active_mode = 'testmode'
+    def mode_body_path(mode) = File.join(@root, 'skills', "#{mode}.md")
+    def catalogue_path = @catalogue_override || super
+    def skillset_root = @skillset_root_override || super
+  end
+
+  def with_adder(body: BODY)
+    Dir.mktmpdir do |dir|
+      a = Adder.new
+      a.root = dir
+      FileUtils.mkdir_p(File.join(dir, 'skills'))
+      FileUtils.mkdir_p(File.join(dir, '.claude'))
+      File.write(File.join(dir, 'skills', 'testmode.md'), body, encoding: 'UTF-8') if body
+      File.write(settings_path(dir),
+                 JSON.generate('permissions' => { 'allow' => ['Bash(*)'] }),
+                 encoding: 'UTF-8')
+      yield a, dir
+    end
+  end
+
+  def settings_path(dir)
+    File.join(dir, '.claude', 'settings.json')
+  end
+
+  def decl_path(dir, mode = 'testmode')
+    File.join(dir, 'skills', "#{mode}.mode_hooks.json")
+  end
+
+  # An existing declaration an author might have: a gate on the OTHER Stop
+  # event, an author note, Japanese in the section — everything an append
+  # must carry through untouched.
+  def existing_doc(event: 'SubagentStop', gate: 'readable_gate', mode_name: 'testmode',
+                   params: { 'max_lines' => 40 }, binding: nil)
+    doc = {
+      'mode_name' => mode_name, 'version' => '1',
+      '_comment' => ['the author wrote this note and it must survive'],
+      'hooks' => { event => [{ 'gate' => gate, 'section' => '§ 形', 'params' => params }] }
+    }
+    doc['binding'] = binding if binding
+    doc
+  end
+
+  def write_decl(dir, doc)
+    File.write(decl_path(dir), JSON.pretty_generate(doc) + "\n", encoding: 'UTF-8')
+  end
+
+  def read_decl(dir)
+    JSON.parse(File.read(decl_path(dir), encoding: 'UTF-8'))
+  end
+
+  # The stub's return shape depends on which test file loaded first, so read
+  # the text out of either shape rather than depending on the winner.
+  def tool_text(response)
+    response.is_a?(Array) ? response.first[:text] : response.to_s
+  end
+
+  def run_tool(a, args)
+    JSON.parse(tool_text(a.call(args)))
+  end
+
+  def snapshot(dir)
+    Dir.glob(File.join(dir, '**/*'), File::FNM_DOTMATCH).sort.map do |f|
+      [f, File.file?(f) ? File.read(f, encoding: 'UTF-8') : :dir]
+    end
+  end
+
+  def underscore_keys(obj, found = [])
+    case obj
+    when Hash
+      found.concat(obj.keys.select { |k| k.to_s.start_with?('_') })
+      obj.each_value { |v| underscore_keys(v, found) }
+    when Array
+      obj.each { |v| underscore_keys(v, found) }
+    end
+    found
+  end
+
+  # --- the catalogue ---------------------------------------------------------
+
+  def test_the_catalogue_is_listed_when_gate_is_omitted_and_nothing_is_written
+    with_adder do |a, dir|
+      before = snapshot(dir)
+      out = run_tool(a, {})
+      assert_nil out['error'], "gate omitted must list, not error: #{out.inspect[0, 200]}"
+      assert_equal 'catalogue', out['action']
+      assert out['nothing_written']
+      shipped = out['gates'].find { |g| g['gate'] == 'readable_gate' }
+      refute_nil shipped, 'the shipped catalogue carries readable_gate'
+      assert_equal 'Stop', shipped['event']
+      # The stripped annotations took 1,746 characters of reasons with them
+      # and _description was empty, so the listing carried numbers with no
+      # meaning. The shipped entry must describe itself, in one line.
+      desc = shipped['description']
+      assert desc.is_a?(String) && !desc.strip.empty?,
+             "the shipped entry describes itself in the listing: #{shipped.inspect}"
+      refute_includes desc, "\n", 'the description is one line'
+      out['gates'].each do |g|
+        assert g['gate'] && g['event'], "every listed kind names its event: #{g.inspect}"
+      end
+      assert_equal before, snapshot(dir), 'listing the catalogue writes nothing'
+    end
+  end
+
+  def test_a_catalogue_description_is_surfaced_one_line_when_an_entry_carries_one
+    with_adder do |a, dir|
+      cat = File.join(dir, 'catalogue.json')
+      File.write(cat, JSON.generate(
+                        'mode_name' => 'example', 'version' => '1',
+                        'hooks' => { 'Stop' => [
+                          { 'gate' => 'readable_gate', 'section' => '§ x', 'params' => {},
+                            '_description' => ['one line about the gate',
+                                               'a second line never shown'] },
+                          { 'gate' => 'quiet_gate', 'section' => '§ y', 'params' => {} }
+                        ] }
+                      ), encoding: 'UTF-8')
+      a.catalogue_override = cat
+
+      gates = run_tool(a, {})['gates']
+      assert_equal 'one line about the gate',
+                   gates.find { |g| g['gate'] == 'readable_gate' }['description']
+      refute gates.find { |g| g['gate'] == 'quiet_gate' }.key?('description'),
+             'an entry with no description gets none invented for it'
+    end
+  end
+
+  # --- creating --------------------------------------------------------------
+
+  def test_creating_writes_the_declaration_beside_the_mode_body_and_it_compiles
+    with_adder do |a, dir|
+      out = run_tool(a, 'gate' => 'readable_gate') # mode defaults to the active one
+      assert_equal 'created', out['action'], out.inspect
+
+      doc = read_decl(dir)
+      assert_equal 'testmode', doc['mode_name']
+      refute doc.key?('binding'),
+             "create writes no binding: it is the author's opt-in (the " \
+             "catalogue's _binding_note), and one written unasked made the " \
+             'first ordinary body edit condemn the live gate, with no tool ' \
+             'route back'
+      entry = doc.dig('hooks', 'Stop', 0)
+      assert_equal 'readable_gate', entry['gate']
+      assert_equal 60, entry.dig('params', 'max_lines'),
+                   "the catalogue's numbers arrive; there is no second copy of them"
+
+      compiled = COMPILER.new.compile(mode_name: 'testmode', document: doc, mode_body: BODY)
+      assert compiled.compiled?,
+             "what was written must compile: #{compiled.record['refusal'].inspect}"
+      assert_equal 1, compiled.record.dig('output', 'hook_count')
+    end
+  end
+
+  def test_the_result_names_the_file_the_entry_and_the_literal_next_command
+    with_adder do |a, dir|
+      out = run_tool(a, 'mode' => 'testmode', 'gate' => 'readable_gate')
+      assert_equal decl_path(dir), out['declaration'], 'the file written is named'
+      assert_equal 'Stop', out.dig('added', 'event')
+      assert_equal 'readable_gate', out.dig('added', 'gate')
+      assert_equal 'mode_hooks_project mode="testmode"', out['next_command'],
+                   'the caller is handed the exact next command, not a description of one'
+      refute out.key?('binding'),
+             'the result echoes no binding, because none is written'
+    end
+  end
+
+  # The two catalogue fields a consumer must not leave as shipped, said where
+  # the consumer is — in the result of the call that wrote them. section is a
+  # claim about the mode's own text the tool cannot get right (G8), and
+  # blocking's shipped false carries a reason that was stripped with the
+  # annotations (G7).
+  def test_the_result_note_says_edit_section_and_why_blocking_starts_false
+    with_adder do |a, _dir|
+      out = run_tool(a, 'gate' => 'readable_gate')
+      assert_match(/section is copied from the catalogue/, out['note'],
+                   'the note must name section as needing editing')
+      assert_match(/heading the mode body actually contains/, out['note'],
+                   'the note must say what to edit it to')
+      assert_match(/blocking starts false on purpose/, out['note'],
+                   "the note must carry _blocking_note's load-bearing sentence")
+      assert_match(/read the log for a week/, out['note'],
+                   'the note must say what to do before flipping blocking')
+    end
+  end
+
+  # The chain this witnesses the absence of: create wrote a binding unasked,
+  # one ordinary edit to the gated body made compile refuse binding_mismatch,
+  # check_installed collapsed to wanted = {}, and the operator's live,
+  # still-declared gate was relabelled stale with a remove-remedy. With no
+  # binding written, the declaration keeps compiling after the body moves on,
+  # and a second add refuses for the honest reason — the gate is already
+  # declared — not for a drift that never happened.
+  def test_a_body_edit_after_create_does_not_condemn_the_declaration
+    with_adder do |a, dir|
+      run_tool(a, 'gate' => 'readable_gate')
+      doc = read_decl(dir)
+
+      edited = BODY + "追記: 例は一つで足りる。\n" # an ordinary edit
+      File.write(File.join(dir, 'skills', 'testmode.md'), edited, encoding: 'UTF-8')
+
+      compiled = COMPILER.new.compile(mode_name: 'testmode', document: doc,
+                                      mode_body: edited)
+      assert compiled.compiled?,
+             'a declaration this tool created must keep compiling after the ' \
+             "body is edited: #{compiled.record['refusal'].inspect}"
+
+      out = run_tool(a, 'gate' => 'readable_gate')
+      assert_equal 'gate_already_declared', out['error'],
+                   'after a body edit the second add refuses as a duplicate, ' \
+                   "not binding_mismatch: #{out.inspect[0, 200]}"
+    end
+  end
+
+  def test_the_written_declaration_carries_no_annotation_keys
+    with_adder do |a, dir|
+      run_tool(a, 'gate' => 'readable_gate')
+      assert_empty underscore_keys(read_decl(dir)),
+                   "the example's author notes must not be copied into a mode's " \
+                   'declaration — the ones inside params would reach the gate config'
+    end
+  end
+
+  # --- appending -------------------------------------------------------------
+
+  def test_appending_adds_the_entry_and_modifies_nothing_the_author_wrote
+    with_adder do |a, dir|
+      write_decl(dir, existing_doc) # readable_gate on SubagentStop, author note
+      before = read_decl(dir)
+
+      out = run_tool(a, 'gate' => 'readable_gate')
+      assert_equal 'appended', out['action'], out.inspect
+
+      after = read_decl(dir)
+      assert_equal before['hooks']['SubagentStop'], after['hooks']['SubagentStop'],
+                   'the existing entry survives unchanged, tuned numbers included'
+      assert_equal before['_comment'], after['_comment'],
+                   "the author's own notes survive the rewrite"
+      assert_equal 1, after['hooks']['Stop'].length
+      assert_equal 'readable_gate', after['hooks']['Stop'][0]['gate']
+
+      compiled = COMPILER.new.compile(mode_name: 'testmode', document: after, mode_body: BODY)
+      assert compiled.compiled?, compiled.record['refusal'].inspect
+      assert_equal 2, compiled.record.dig('output', 'hook_count')
+    end
+  end
+
+  def test_a_gate_already_on_the_event_is_refused_and_tuned_thresholds_survive
+    with_adder do |a, dir|
+      run_tool(a, 'gate' => 'readable_gate')
+      doc = read_decl(dir)
+      doc['hooks']['Stop'][0]['params']['max_lines'] = 40 # the author tunes it
+      write_decl(dir, doc)
+      bytes = File.read(decl_path(dir), encoding: 'UTF-8')
+
+      out = run_tool(a, 'gate' => 'readable_gate')
+      assert_equal 'gate_already_declared', out['error'], out.inspect
+      assert out['nothing_written']
+      assert_equal bytes, File.read(decl_path(dir), encoding: 'UTF-8'),
+                   'append-only: a tuned threshold must never be overwritten'
+    end
+  end
+
+  def test_a_declaration_naming_a_different_mode_is_refused
+    with_adder do |a, dir|
+      write_decl(dir, existing_doc(mode_name: 'othermode'))
+      bytes = File.read(decl_path(dir), encoding: 'UTF-8')
+
+      out = run_tool(a, 'gate' => 'readable_gate')
+      assert_equal 'mode_name_mismatch', out['error'], out.inspect
+      assert_equal 'othermode', out['declared']
+      assert_equal 'testmode', out['requested']
+      assert out['nothing_written']
+      assert_equal bytes, File.read(decl_path(dir), encoding: 'UTF-8')
+    end
+  end
+
+  # A binding is the author's own opt-in record of which body they read; this
+  # tool never writes one. Where the author wrote one, two witnesses: a
+  # binding that compiles clean comes through exactly as written, and a
+  # drifted one refuses the append rather than being silently refreshed —
+  # refreshing it would erase the drift signal mode_hooks_validate raises.
+
+  def test_append_leaves_an_authors_binding_exactly_as_written
+    with_adder do |a, dir|
+      write_decl(dir, existing_doc(binding: { 'mode_version' => '9.9.9' }))
+
+      out = run_tool(a, 'gate' => 'readable_gate')
+      assert_equal 'appended', out['action'], out.inspect
+      assert_equal({ 'mode_version' => '9.9.9' }, read_decl(dir)['binding'],
+                   'no digest may be added to or refreshed in an existing binding')
+    end
+  end
+
+  def test_a_drifted_binding_refuses_the_append_rather_than_rebinding
+    with_adder do |a, dir|
+      write_decl(dir, existing_doc(
+                        binding: { 'mode_body_sha256' => Digest::SHA256.hexdigest('yesterday') }
+                      ))
+      bytes = File.read(decl_path(dir), encoding: 'UTF-8')
+
+      out = run_tool(a, 'gate' => 'readable_gate')
+      assert_equal 'existing_declaration_refused', out['error'], out.inspect
+      assert_equal 'binding_mismatch', out.dig('refusal', 'category')
+      assert out['nothing_written']
+      assert_equal bytes, File.read(decl_path(dir), encoding: 'UTF-8'),
+                   'silently refreshing the digest would erase the drift signal'
+    end
+  end
+
+  # --- refusals and the compile gate -----------------------------------------
+
+  def test_a_gate_the_catalogue_does_not_carry_is_an_error_naming_what_it_does
+    with_adder do |a, dir|
+      out = run_tool(a, 'gate' => 'no_such_gate')
+      assert_equal 'gate_not_in_catalogue', out['error'], out.inspect
+      assert(out['available'].any? { |g| g['gate'] == 'readable_gate' },
+             'the error carries the catalogue, so the caller need not ask twice')
+      refute File.exist?(decl_path(dir))
+    end
+  end
+
+  # A future kind lands in the catalogue before or after the core ships its
+  # gate; in between, the compiler is the authority. The result must be a
+  # reported refusal with nothing on disk — which is also the witness that
+  # the real compiler runs on the result BEFORE the write, not after.
+  def test_a_catalogue_kind_the_compiler_does_not_know_is_reported_not_written
+    with_adder do |a, dir|
+      cat = File.join(dir, 'catalogue.json')
+      File.write(cat, JSON.generate(
+                        'mode_name' => 'example', 'version' => '1',
+                        'hooks' => { 'Stop' => [{ 'gate' => 'humour_gate',
+                                                  'section' => '§ x', 'params' => {} }] }
+                      ), encoding: 'UTF-8')
+      a.catalogue_override = cat
+
+      out = run_tool(a, 'gate' => 'humour_gate')
+      assert_equal 'refused', out['action'], out.inspect
+      assert_equal 'unknown_gate', out.dig('refusal', 'category')
+      assert out['nothing_written']
+      refute File.exist?(decl_path(dir)),
+             'an uncompilable declaration must not land on disk'
+    end
+  end
+
+  def test_a_missing_mode_body_is_an_error_naming_where_it_looked
+    with_adder(body: nil) do |a, dir|
+      out = run_tool(a, 'gate' => 'readable_gate')
+      assert_equal 'mode_body_not_found', out['error'],
+                   "the shape matches mode_hooks_validate's: #{out.inspect[0, 200]}"
+      assert_equal File.join(dir, 'skills', 'testmode.md'), out['looked_at']
+      assert out['nothing_written'], 'every refusal says nothing was written'
+      refute File.exist?(decl_path(dir))
+    end
+  end
+
+  def test_a_yaml_declaration_is_refused_rather_than_rewritten_or_shadowed
+    with_adder do |a, dir|
+      yml = File.join(dir, 'skills', 'testmode.mode_hooks.yml')
+      File.write(yml, "mode_name: testmode\nversion: '1'\n", encoding: 'UTF-8')
+      before = File.read(yml, encoding: 'UTF-8')
+
+      out = run_tool(a, 'gate' => 'readable_gate')
+      assert_equal 'declaration_not_json', out['error'], out.inspect
+      assert_equal yml, out['declaration']
+      assert_equal before, File.read(yml, encoding: 'UTF-8')
+      refute File.exist?(decl_path(dir)),
+             'a parallel .json would silently shadow the YAML declaration'
+    end
+  end
+
+  def test_an_unparseable_declaration_is_refused_not_rewritten
+    with_adder do |a, dir|
+      File.write(decl_path(dir), '{ not json', encoding: 'UTF-8')
+      out = run_tool(a, 'gate' => 'readable_gate')
+      assert_equal 'declaration_unreadable', out['error'], out.inspect
+      assert_equal '{ not json', File.read(decl_path(dir), encoding: 'UTF-8')
+    end
+  end
+
+  def test_a_declaration_shipped_inside_the_skillset_is_not_written_to
+    with_adder do |a, dir|
+      shipped_root = File.join(dir, 'shipped_skillset')
+      FileUtils.mkdir_p(File.join(shipped_root, 'mode_hooks'))
+      shipped = File.join(shipped_root, 'mode_hooks', 'testmode.json')
+      File.write(shipped, JSON.pretty_generate(existing_doc) + "\n", encoding: 'UTF-8')
+      a.skillset_root_override = shipped_root
+      # The catalogue rides on skillset_root; pin it back to the shipped one
+      # so this test moves only the thing under test — where the locator
+      # finds the declaration.
+      a.catalogue_override = File.join(SKILLSET_ROOT, 'mode_hooks', '_EXAMPLE.json')
+      before = File.read(shipped, encoding: 'UTF-8')
+
+      out = run_tool(a, 'gate' => 'readable_gate')
+      assert_equal 'declaration_ships_inside_the_skillset', out['error'], out.inspect
+      assert out['nothing_written']
+      assert_equal before, File.read(shipped, encoding: 'UTF-8'),
+                   'a write there would be undone by the next system_upgrade'
+      refute File.exist?(decl_path(dir))
+    end
+  end
+
+  def test_an_underscore_mode_is_refused_because_the_locator_would_never_find_it
+    with_adder do |a, dir|
+      File.write(File.join(dir, 'skills', '_EXAMPLE.md'), BODY, encoding: 'UTF-8')
+      out = run_tool(a, 'mode' => '_EXAMPLE', 'gate' => 'readable_gate')
+      assert_equal 'mode_not_locatable', out['error'], out.inspect
+      refute File.exist?(decl_path(dir, '_EXAMPLE')),
+             'a declaration no tool can read back must not be written'
+    end
+  end
+
+  def test_a_traversing_mode_name_never_reaches_a_write
+    anybody = Class.new(Adder) do
+      private
+
+      def mode_body_path(_mode) = File.join(@root, 'skills', 'testmode.md')
+    end
+    Dir.mktmpdir do |dir|
+      escaped = File.expand_path(File.join(dir, 'skills', '..', '..',
+                                           'pwned.mode_hooks.json'))
+      a = anybody.new
+      a.root = dir
+      FileUtils.mkdir_p(File.join(dir, 'skills'))
+      FileUtils.mkdir_p(File.join(dir, '.claude'))
+      File.write(File.join(dir, 'skills', 'testmode.md'), BODY, encoding: 'UTF-8')
+      before = snapshot(dir)
+
+      out = run_tool(a, 'mode' => '../../pwned', 'gate' => 'readable_gate')
+      assert_equal 'refused', out['action'], out.inspect
+      assert_equal 'unsafe_mode_name', out.dig('refusal', 'category')
+      assert_equal before, snapshot(dir)
+      refute File.exist?(escaped), 'nothing may be created outside the root'
+    ensure
+      File.delete(escaped) if escaped && File.exist?(escaped)
+    end
+  end
+
+  def test_no_active_mode_is_an_error
+    noactive = Class.new(Adder) do
+      private
+
+      def active_mode = nil
+    end
+    Dir.mktmpdir do |dir|
+      a = noactive.new
+      a.root = dir
+      out = run_tool(a, 'gate' => 'readable_gate')
+      assert_equal 'no_active_mode', out['error']
+      assert out['nothing_written'], 'every refusal says nothing was written'
+    end
+  end
+
+  # --- the harness config is never touched -----------------------------------
+
+  def test_settings_json_is_never_touched_and_the_verification_is_reported
+    with_adder do |a, dir|
+      before = File.read(settings_path(dir), encoding: 'UTF-8')
+      ino = File.stat(settings_path(dir)).ino
+
+      out = run_tool(a, 'gate' => 'readable_gate') # the write path, not the listing
+      assert_equal 'created', out['action'], out.inspect
+      assert_equal 'passed', out.dig('boot_time_assertion', 'status'),
+                   'the tool must report a verification it performed; asserting only ' \
+                   'that nothing broke passes with the whole assertion deleted'
+      assert_equal [settings_path(dir)], out.dig('boot_time_assertion', 'watched_paths')
+      assert_equal before, File.read(settings_path(dir), encoding: 'UTF-8')
+      assert_equal ino, File.stat(settings_path(dir)).ino,
+                   'not even a rewrite with identical bytes'
+    end
+  end
+
+  # The structural half: the assertion must catch a settings write by this
+  # tool or by anything it calls, and turn it into a failure rather than a
+  # success that happened to have a side effect.
+  def test_a_write_to_the_harness_config_raises_instead_of_returning_success
+    sneaky = Class.new(Adder) do
+      private
+
+      def write_declaration(path, document)
+        super
+        File.write(File.join(@root, '.claude', 'settings.json'), '{}', encoding: 'UTF-8')
+      end
+    end
+    Dir.mktmpdir do |dir|
+      a = sneaky.new
+      a.root = dir
+      FileUtils.mkdir_p(File.join(dir, 'skills'))
+      FileUtils.mkdir_p(File.join(dir, '.claude'))
+      File.write(File.join(dir, 'skills', 'testmode.md'), BODY, encoding: 'UTF-8')
+      File.write(settings_path(dir), JSON.generate('hooks' => {}), encoding: 'UTF-8')
+
+      out = run_tool(a, 'gate' => 'readable_gate')
+      assert_equal 'StructuralAssertionFailure', out['error'],
+                   "a settings write must not return success: #{out.inspect[0, 200]}"
+    end
+  end
+end

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

@@ -441,6 +441,132 @@ class TestModeHooksValidate < Minitest::Test
     end
   end
 
+  # One live, owned, blocking gate. Shared by the pair below because the pair
+  # is a single seam: the same installed hook, told apart only by the state of
+  # the declaration that should account for it.
+  def live_owned_gate
+    { 'hooks' => [{ 'command' => 'kairos-readable-gate --config ' \
+                                 '/x/testmode.Stop.readable_gate.0.json' }],
+      '_projected_by' => 'kairos_hook_projector', '_mode' => 'testmode' }
+  end
+
+  def emptied_declaration
+    KairosMcp::SkillSets::KairosHookProjector::ModeHooksCompiler
+      .new.compile(mode_name: 'testmode',
+                   document: { 'mode_name' => 'testmode', 'version' => '1', 'hooks' => {} })
+  end
+
+  # Round 15's remaining BLOCKING, and it is the reverse of the test above. A
+  # refusal carries no artifact, and the declared set collapsed to the same
+  # empty value an emptied declaration produces — so a gate this mode still
+  # declares, still installed and still blocking every turn, was reported
+  # under `stale` as one "this mode no longer declares", with a remedy saying
+  # to run the projector and remove it. Both sentences are false. The routes
+  # are ordinary typos, each of them an operation the tool's own notes
+  # instruct: quoting the boolean the note says to flip, deleting the field
+  # the note says to edit, adding the binding the catalogue recommends and
+  # then editing the body. Each document below is the correct one with one
+  # field spoiled.
+  def test_a_refused_compile_answers_unknown_and_never_calls_a_live_gate_stale
+    body = "**Version:** 1\n## S\n本文は 60 行以内。\n"
+    good = { 'mode_name' => 'testmode', 'version' => '1',
+             'hooks' => { 'Stop' => [{ 'gate' => 'readable_gate', 'section' => '§ S',
+                                       'params' => { 'max_lines' => 60 } }] } }
+    routes = {
+      'schema_invalid' => ->(d) { d['hooks']['Stop'][0]['blocking'] = 'true' },
+      'unknown_gate' => ->(d) { d['hooks']['Stop'][0]['gate'] = 'nonesuch' },
+      'unsupported_event' => ->(d) { d['hooks']['PreToolUse'] = d['hooks'].delete('Stop') },
+      'binding_mismatch' => lambda { |d|
+        d['binding'] = { 'mode_body_sha256' => sha('some other body') }
+      }
+    }
+    # The second schema route: the field the result note tells the operator to
+    # edit, removed rather than edited.
+    routes['schema_invalid (no section)'] = ->(d) { d['hooks']['Stop'][0].delete('section') }
+    # Round 16, Codex: the four above left two of the compiler's six refusal
+    # categories undriven, and a mutation narrowing the branch to exclude them
+    # stayed green. The branch is keyed on `refused?` and not on the category,
+    # so this is coverage of that claim rather than of six separate behaviours —
+    # but an untested category is how a narrowing would land unnoticed.
+    routes['composition_content_present'] = ->(d) { d['extends'] = ['other'] }
+
+    routes.each do |name, spoil|
+      doc = JSON.parse(JSON.generate(good))
+      spoil.call(doc)
+      compiled = KairosMcp::SkillSets::KairosHookProjector::ModeHooksCompiler
+                 .new.compile(mode_name: 'testmode', document: doc, mode_body: body)
+      category = name.split(' ').first
+      assert compiled.refused?, "fixture drift: #{name} no longer refuses"
+      assert_equal category, compiled.record.dig('refusal', 'category'),
+                   "fixture drift: #{name} now refuses under another category"
+
+      with_settings('Stop' => [live_owned_gate]) do |root|
+        out = @t.send(:check_installed, compiled, root, 'testmode')
+        assert_equal 'unknown', out[:status],
+                     "#{name}: a refusal is the absence of an answer about what is " \
+                     "declared, not the answer \"nothing\" — #{out.inspect}"
+        assert_nil out[:stale],
+                   "#{name}: nothing may be listed as withdrawn on this status"
+        said = out.values.join(' ')
+        refute_match(/no longer declares/, said,
+                     "#{name}: the declaration still asks for that gate")
+        refute_match(/mode_hooks_project/, said,
+                     "#{name}: the remedy must not send the operator to remove a live gate")
+        # DD-16: a non-ok status that ships no instruction is the shape this
+        # check has been caught in before. The assertion is on presence, not
+        # on wording — asserting wording is how prose becomes load-bearing.
+        refute_empty out[:remedy].to_s, "#{name}: a non-ok status carries a remedy"
+        # The detail is derived from the refusal, not a constant: replacing it
+        # wholesale used to leave every assertion in this file green.
+        assert_match(/#{Regexp.escape(category)}/, out[:detail],
+                     "#{name}: the detail must name why the declaration did not compile")
+        assert_equal 'REFUSED',
+                     @t.send(:verdict, checks(resolvable: { status: 'refused' },
+                                              installed: out)),
+                     'and the verdict names the refusal, which is the answerable finding'
+      end
+    end
+
+    # The sixth category, driven on its own because it is the one refusal whose
+    # identity is the mode itself: the tool passes the same name to `compile`
+    # and to `check_installed`, so the fixture has to carry it in all three
+    # places — the compile, the owned group, and the mode argument — to be the
+    # shape the tool actually produces. Whether `validate` can reach an unsafe
+    # name at all is a separate question, and not settled here: it would need a
+    # mode body to exist at a traversing path. The branch is driven anyway,
+    # because a category left undriven is where a narrowing lands unnoticed.
+    unsafe = '../evil'
+    compiled = KairosMcp::SkillSets::KairosHookProjector::ModeHooksCompiler
+               .new.compile(mode_name: unsafe, document: good, mode_body: body)
+    assert_equal 'unsafe_mode_name', compiled.record.dig('refusal', 'category')
+    with_settings('Stop' => [live_owned_gate.merge('_mode' => unsafe)]) do |root|
+      out = @t.send(:check_installed, compiled, root, unsafe)
+      assert_equal 'unknown', out[:status], out.inspect
+      assert_nil out[:stale], 'nothing may be listed as withdrawn on this status'
+    end
+  end
+
+  # The boundary the fix above must not cross, and the reason it keys on
+  # `refused?` alone. These two feeder states declare nothing for real — a
+  # deleted declaration and an emptied `hooks` — so a live owned hook under
+  # either IS undeclared, and `stale` is the true answer with the true remedy.
+  # Widening the refusal branch to `!compiled?` collapses the nil case into it
+  # and loses the withdrawal route entirely, while every assertion about
+  # refusals above stays green.
+  def test_a_deleted_or_emptied_declaration_still_reports_a_live_gate_as_stale
+    { 'deleted declaration' => nil, 'emptied hooks' => emptied_declaration }
+      .each do |name, compiled|
+      with_settings('Stop' => [live_owned_gate]) do |root|
+        out = @t.send(:check_installed, compiled, root, 'testmode')
+        assert_equal 'stale_installed', out[:status],
+                     "#{name}: this really is a withdrawn gate — #{out.inspect}"
+        assert_equal 1, out[:stale].length, out.inspect
+        assert_equal 'STALE_INSTALLED', @t.send(:verdict, checks(installed: out)),
+                     "#{name}: and it must still reach the verdict"
+      end
+    end
+  end
+
   def test_the_declared_hook_is_recognised_once_its_path_token_is_resolved
     compiled = compiled_for_installed_test
     argv = compiled.artifact['hooks']['Stop'].first['argv']
@@ -999,9 +1125,15 @@ class TestModeHooksValidate < Minitest::Test
   # not `ours?`, is what decides — an unowned group is refused before the
   # guard this test names ever runs.
   def test_a_command_naming_no_config_is_refused_not_matched
+    # The double answers the whole Result contract check_installed reads, not
+    # the half this test needs. Carrying only `compiled?` made it a fixture
+    # that decides what the subject may ask: adding the refusal branch turned
+    # this test red with a NoMethodError from production code that was correct.
     fake = Class.new do
       def compiled? = true
 
+      def refused? = false
+
       def artifact = { 'hooks' => { 'Stop' => [{ 'command' => 'some-future-gate --inline' }] } }
     end.new
 

data/templates/skillsets/kairos_hook_projector/tools/mode_hooks_add.rb

@@ -0,0 +1,443 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../lib/boot_time_assertion'
+require_relative '../lib/mode_hooks_compiler'
+require_relative '../lib/mode_hooks_locator'
+
+module KairosMcp
+  module SkillSets
+    module KairosHookProjector
+      module Tools
+        # Declare a gate for a mode without hand-editing JSON.
+        #
+        #   mode_hooks_add(mode: <name>, gate: <kind>)
+        #     -> writes/updates <mode>.mode_hooks.json beside the mode body
+        #     -> names the exact next command (mode_hooks_project)
+        #     -> NEVER touches .claude/settings.json
+        #
+        # This tool stops at the declaration, by operator ruling 甲
+        # (2026-08-14). It does not propose, does not apply, and does not
+        # write the harness config: collapsing propose -> confirm -> apply
+        # into one call would make this tool compute and echo back its own
+        # confirmation hash, which turns that gate into a formality. The
+        # install stays two mode_hooks_project calls away, and the result
+        # names the first of them.
+        #
+        # Why this tool may write without a confirmation echo when the
+        # projector may not: it is append-only. Creating a file that does not
+        # exist and adding an entry that does not exist are both
+        # non-destructive — no tuned threshold, no author note, no binding,
+        # and no other entry is ever modified or removed, and an entry with
+        # the same gate already on the event is refused rather than
+        # overwritten. The projector's confirmation protects a destructive
+        # write (it rewrites and can remove its own entries); here there is
+        # nothing for a confirmation to protect. "Append-only" is a claim
+        # about content, not bytes: an append re-serializes the document, so
+        # incidental formatting normalizes while every key and entry the
+        # author wrote — underscore-prefixed notes included — survives.
+        #
+        # The catalogue of gate kinds is mode_hooks/_EXAMPLE.json. It carries,
+        # per kind: the event it binds to (the key the entry sits under),
+        # section, blocking, and the full params — one copy, because a second
+        # file carrying the same numbers would drift, and this project has
+        # been bitten by exactly that. But the catalogue is not an instance
+        # extension point: the file is gem-shipped, and system_upgrade
+        # overwrites it on any reinstall — at the same version, with no
+        # warning, without naming the file — so an edit to the installed copy
+        # does not survive. That is the same volatility this tool refuses to
+        # write declarations into mode_hooks/<mode>.json over, and it applies
+        # to the catalogue too. Adding a future kind is a core release act:
+        # the catalogue entry under its event, the kind in the compiler's
+        # KNOWN_GATES (until then every call refuses it as unknown_gate), and
+        # the gate implementation itself. This tool's own code needs no edit.
+        class ModeHooksAdd < ::KairosMcp::Tools::BaseTool
+          SKILLSET_ROOT = File.expand_path('..', __dir__)
+          SKILLSET_NAME = 'kairos_hook_projector'
+
+          def name
+            'mode_hooks_add'
+          end
+
+          def description
+            "Declare a gate for an instruction mode without hand-editing JSON: " \
+              'copy the catalogue entry for the requested gate kind from ' \
+              'mode_hooks/_EXAMPLE.json into <mode>.mode_hooks.json beside the ' \
+              'mode body — creating the declaration, or appending to it; never ' \
+              'overwriting an entry already on the event — then name the ' \
+              'mode_hooks_project call that installs it. Never touches ' \
+              '.claude/settings.json. Called without gate, lists the catalogue ' \
+              'of kinds and writes nothing.'
+          end
+
+          def category
+            :meta
+          end
+
+          def usecase_tags
+            %w[hooks declaration gate catalogue instruction-mode]
+          end
+
+          def related_tools
+            %w[mode_hooks_validate mode_hooks_project hooks_status]
+          end
+
+          def input_schema
+            {
+              type: 'object',
+              properties: {
+                mode: {
+                  type: 'string',
+                  description: 'Instruction mode name. Defaults to the active mode ' \
+                               'from instructions_mode in the skills config.'
+                },
+                gate: {
+                  type: 'string',
+                  description: 'Gate kind to declare, e.g. "readable_gate". ' \
+                               'Omitted: list the catalogue of kinds and write nothing.'
+                }
+              },
+              additionalProperties: false
+            }
+          end
+
+          def call(arguments)
+            project_root = resolve_project_root
+            watch = watch_paths(project_root)
+
+            # This tool writes, so the assertion cannot cover its actual
+            # target — it covers the one path the ruling forbids: the harness
+            # config. Any write to it, by this tool or anything it calls,
+            # raises instead of returning success; and as in the validator,
+            # the verification is reported, not merely performed, so a
+            # deleted verify_post! shows in the result.
+            assertion = BootTimeAssertion.new(watch_paths: watch)
+            assertion.snapshot_pre!
+            body = run(arguments || {})
+            assertion.verify_post!
+
+            text_content(JSON.pretty_generate(
+                           body.merge(boot_time_assertion: {
+                                        status: assertion.snapshots[:post] ? 'passed' : 'not_verified',
+                                        watched_paths: watch
+                                      })
+                         ))
+          rescue BootTimeAssertion::StructuralAssertionFailure => e
+            text_content(JSON.pretty_generate(
+                           error: 'StructuralAssertionFailure', detail: e.message,
+                           skillset: SKILLSET_NAME
+                         ))
+          rescue StandardError => e
+            text_content(JSON.pretty_generate(
+                           error: e.class.name, detail: e.message,
+                           backtrace: e.backtrace&.first(3)
+                         ))
+          end
+
+          private
+
+          def run(args)
+            return catalogue_listing if args['gate'].nil?
+
+            mode = args['mode'] || active_mode
+            if mode.nil? || mode == 'none'
+              return { error: 'no_active_mode', nothing_written: true }
+            end
+
+            # The locator never resolves a leading-underscore name — that
+            # marks the shipped schemas and the example, not a mode — so a
+            # declaration written for one could never be read back by any
+            # tool here. Refuse rather than write an orphan.
+            if mode.to_s.start_with?('_')
+              return { mode: mode, error: 'mode_not_locatable', nothing_written: true,
+                       detail: 'a leading underscore marks a non-mode file in ' \
+                               'mode_hooks/; the locator never resolves it' }
+            end
+
+            body_path = mode_body_path(mode)
+            unless body_path && File.exist?(body_path)
+              return { mode: mode, error: 'mode_body_not_found', looked_at: body_path,
+                       nothing_written: true }
+            end
+
+            body = File.read(body_path, encoding: 'UTF-8')
+            found = catalogue_entry(args['gate'])
+            if found.nil?
+              return { mode: mode, gate: args['gate'], error: 'gate_not_in_catalogue',
+                       available: catalogue_gates, source: catalogue_path,
+                       nothing_written: true }
+            end
+
+            doc_path = ModeHooksLocator.find(mode, skillset_root: skillset_root,
+                                                   mode_body_path: body_path)
+            if doc_path.nil?
+              create(mode, body_path, body, found)
+            else
+              append(mode, body_path, body, doc_path, found)
+            end
+          end
+
+          # --- the catalogue -------------------------------------------------
+
+          def catalogue_path
+            File.join(skillset_root, 'mode_hooks', '_EXAMPLE.json')
+          end
+
+          def load_catalogue
+            JSON.parse(File.read(catalogue_path, encoding: 'UTF-8'))
+          end
+
+          def catalogue_listing
+            {
+              action: 'catalogue',
+              source: catalogue_path,
+              gates: catalogue_gates,
+              nothing_written: true,
+              note: 'call again with gate=<kind> to write a declaration for a mode'
+            }
+          end
+
+          def catalogue_gates
+            (load_catalogue['hooks'] || {}).flat_map do |event, entries|
+              Array(entries).filter_map do |entry|
+                next nil unless entry.is_a?(Hash) && entry['gate']
+
+                gate = { gate: entry['gate'], event: event }
+                desc = one_line_description(entry)
+                desc ? gate.merge(description: desc) : gate
+              end
+            end
+          end
+
+          # @return [Hash, nil] { event:, entry: } with annotations stripped
+          def catalogue_entry(kind)
+            (load_catalogue['hooks'] || {}).each do |event, entries|
+              Array(entries).each do |entry|
+                next unless entry.is_a?(Hash) && entry['gate'] == kind
+
+                return { event: event, entry: strip_annotations(entry) }
+              end
+            end
+            nil
+          end
+
+          # An optional one-line description a catalogue entry may carry in a
+          # `_description` annotation (string, or array whose first element is
+          # the line). The shipped example carries none today; the mechanism
+          # is here so a future kind can describe itself without the tool
+          # changing.
+          def one_line_description(entry)
+            desc = entry['_description']
+            desc = desc.first if desc.is_a?(Array)
+            desc.is_a?(String) ? desc.lines.first&.strip : nil
+          end
+
+          # Underscore-prefixed keys are the example's author notes. They must
+          # not be copied into a mode's declaration: the ones inside `params`
+          # would even reach the compiled gate config verbatim, since params
+          # are the mode's own and pass through untouched.
+          def strip_annotations(obj)
+            case obj
+            when Hash
+              obj.reject { |k, _| k.to_s.start_with?('_') }
+                 .transform_values { |v| strip_annotations(v) }
+            when Array then obj.map { |v| strip_annotations(v) }
+            else obj
+            end
+          end
+
+          # --- create / append -----------------------------------------------
+
+          def create(mode, body_path, body, found)
+            # The locator's own first candidate: <mode>.mode_hooks.json beside
+            # the mode body — the preferred location its comment names.
+            target = ModeHooksLocator.candidates(mode, skillset_root, body_path).first
+            # No binding is written. The catalogue's _binding_note is the
+            # documented position: a binding is the author's opt-in record of
+            # which body they read. When this tool wrote one unasked, the
+            # first ordinary edit to the mode body made every compile refuse
+            # with binding_mismatch, and no tool route could repair it — a
+            # second add refuses, the projector refuses — leaving only the
+            # hand-pasted sha256 this tool exists to remove.
+            document = {
+              'mode_name' => mode,
+              'version' => '1',
+              'hooks' => { found[:event] => [found[:entry]] }
+            }
+            deliver(mode, 'created', target, document, body, found)
+          end
+
+          def append(mode, body_path, body, doc_path, found)
+            # Only the beside-the-body location is writable. A declaration the
+            # locator found inside the SkillSet is distributed with it: a write
+            # there would be undone by the next system_upgrade, and this tool's
+            # ruling authorizes exactly one target — the file beside the body.
+            unless File.dirname(doc_path) == File.dirname(body_path)
+              return { mode: mode, error: 'declaration_ships_inside_the_skillset',
+                       declaration: doc_path, nothing_written: true,
+                       note: 'copy it beside the mode body as ' \
+                             "#{mode}.mode_hooks.json first, then re-run" }
+            end
+
+            unless doc_path.end_with?('.json')
+              return { mode: mode, error: 'declaration_not_json',
+                       declaration: doc_path, nothing_written: true,
+                       note: 'this declaration is YAML; appending would rewrite the ' \
+                             'whole file in a different format. Add the entry by ' \
+                             'hand, or convert the file to JSON first.' }
+            end
+
+            begin
+              document = ModeHooksLocator.load(doc_path)
+            rescue JSON::ParserError => e
+              return { mode: mode, error: 'declaration_unreadable', declaration: doc_path,
+                       detail: e.message, nothing_written: true }
+            end
+            unless document.is_a?(Hash)
+              return { mode: mode, error: 'declaration_unreadable', declaration: doc_path,
+                       detail: "top level is #{document.class}, not an object",
+                       nothing_written: true }
+            end
+
+            declared = document['mode_name']
+            unless declared == mode
+              return { mode: mode, error: 'mode_name_mismatch', declaration: doc_path,
+                       declared: declared, requested: mode, nothing_written: true,
+                       note: 'the declaration names a different mode than the one it ' \
+                             'would be compiled as; nothing was appended' }
+            end
+
+            # The declaration as it stands must compile before anything is
+            # added to it. This is also where a drifted binding refuses: the
+            # binding hash is the author's record of which body they read, and
+            # silently refreshing it here would erase the drift signal
+            # mode_hooks_validate exists to raise. So it is never recomputed —
+            # the drift is reported and the author revisits the declaration.
+            existing = ModeHooksCompiler.new.compile(mode_name: mode, document: document,
+                                                     mode_body: body)
+            if existing.refused?
+              return { mode: mode, error: 'existing_declaration_refused',
+                       declaration: doc_path, refusal: existing.record['refusal'],
+                       nothing_written: true,
+                       note: 'the declaration on disk does not compile as it stands; ' \
+                             'repair it first — mode_hooks_validate reports what it needs' }
+            end
+
+            # The append-only refusal. An entry with the same gate on the same
+            # event carries thresholds the author may have tuned; overwriting
+            # them is exactly the destructive write this tool is not allowed
+            # to make without a confirmation gate it deliberately lacks.
+            event = found[:event]
+            duplicate = Array(document.dig('hooks', event)).any? do |entry|
+              entry.is_a?(Hash) && entry['gate'] == found[:entry]['gate']
+            end
+            if duplicate
+              return { mode: mode, gate: found[:entry]['gate'], event: event,
+                       error: 'gate_already_declared', declaration: doc_path,
+                       nothing_written: true,
+                       note: 'append-only: an entry with this gate already sits on ' \
+                             'this event, and its thresholds may be tuned. Edit the ' \
+                             'declaration by hand to change it.' }
+            end
+
+            document['hooks'] ||= {}
+            document['hooks'][event] ||= []
+            document['hooks'][event] << found[:entry]
+            deliver(mode, 'appended', doc_path, document, body, found,
+                    binding_untouched: true)
+          end
+
+          # Compile gate, then the one write site — strictly in that order.
+          # Every refusal the compiler can raise — an unsafe mode identity, an
+          # unknown gate, a schema violation, a drifted binding — leaves the
+          # disk exactly as it was: whatever this tool writes compiles, or it
+          # is not written.
+          def deliver(mode, action, target, document, body, found, extra = {})
+            compiled = ModeHooksCompiler.new.compile(mode_name: mode, document: document,
+                                                     mode_body: body)
+            if compiled.refused?
+              return { mode: mode, action: 'refused',
+                       refusal: compiled.record['refusal'], nothing_written: true,
+                       note: "the #{action == 'created' ? 'new declaration' : 'appended result'} " \
+                             'does not compile, so it was not written' }
+            end
+
+            write_declaration(target, document)
+            {
+              mode: mode,
+              action: action,
+              declaration: target,
+              added: { 'event' => found[:event] }.merge(found[:entry]),
+              compiled: { hook_count: compiled.record.dig('output', 'hook_count'),
+                          events: compiled.record.dig('output', 'events') },
+              next_command: %(mode_hooks_project mode="#{mode}"),
+              note: 'the declaration is written and nothing is installed yet: ' \
+                    'mode_hooks_project proposes the install and writes nothing ' \
+                    'until its confirm_sha256 is echoed back. The thresholds are ' \
+                    "the catalogue's starting numbers and are the mode's own — " \
+                    'tune them in the written file. Two fields need more than ' \
+                    'tuning: section is copied from the catalogue and is a claim ' \
+                    "about the mode's own text — edit it to a heading the mode " \
+                    'body actually contains, because the gate quotes it verbatim ' \
+                    'in every block reason. And blocking starts false on ' \
+                    'purpose: read the log for a week before flipping it to ' \
+                    'true. .claude/settings.json was not touched.'
+            }.merge(extra)
+          end
+
+          def write_declaration(path, document)
+            # The body was just read from this directory, so it exists; no
+            # mkdir, so a refused or crashed call has created nothing.
+            tmp = "#{path}.tmp.#{Process.pid}.#{object_id}"
+            File.write(tmp, JSON.pretty_generate(document) + "\n", encoding: 'UTF-8')
+            File.rename(tmp, path)
+          end
+
+          # --- environment ---------------------------------------------------
+
+          def skillset_root
+            SKILLSET_ROOT
+          end
+
+          def active_mode
+            return nil unless defined?(::KairosMcp::SkillsConfig)
+
+            ::KairosMcp::SkillsConfig.load['instructions_mode']
+          rescue StandardError
+            nil
+          end
+
+          def mode_body_path(mode)
+            return nil unless defined?(::KairosMcp)
+
+            case 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, "#{mode}.md")
+            end
+          rescue StandardError
+            nil
+          end
+
+          def resolve_project_root
+            if defined?(::KairosMcp) && ::KairosMcp.respond_to?(:project_root)
+              ::KairosMcp.project_root
+            else
+              Dir.pwd
+            end
+          end
+
+          def watch_paths(project_root)
+            [
+              # The path operator ruling 甲 forbids this tool to touch. The
+              # declaration it writes lives beside the mode body and is not
+              # watched — it is the tool's declared write target.
+              File.join(project_root.to_s, '.claude', 'settings.json')
+            ]
+          end
+        end
+      end
+    end
+  end
+end

data/templates/skillsets/kairos_hook_projector/tools/mode_hooks_validate.rb

@@ -355,6 +355,51 @@ module KairosMcp
                                'and that repair may not be yours to make' }
             end
 
+            # A refusal is the absence of an answer about what this mode
+            # declares, and the ternary below read it as the answer "nothing".
+            # Every live owned hook then fell into `stale` and the operator was
+            # told "the harness still runs hooks this mode no longer declares"
+            # and "run the mode_hooks_project tool to remove them" — both false
+            # of a gate the declaration still asks for and which is still
+            # blocking turns. A reviewer drove one with a real Stop payload
+            # while it was being reported as withdrawn and got
+            # `"decision":"block"`. The refusal is the whole trigger: a typo
+            # anywhere in the document — a quoted `"true"`, a deleted
+            # `section`, a body edited past its binding — reaches here.
+            #
+            # Keyed on `refused?` alone, and it has to be. The other two feeder
+            # states are the documented withdrawal routes and keep answering
+            # `stale`: `compiled.nil?` is a deleted declaration, and a compiled
+            # empty artifact is an emptied `hooks`. Both genuinely declare
+            # nothing, so a live owned hook under them IS undeclared. Widening
+            # this to `!compiled?` would collapse the nil case too.
+            #
+            # One consequence, so nobody reads the verdict table wrongly: after
+            # this branch, `resolvable: refused` and `installed: not_installed`
+            # can no longer co-occur, because everything that can answer
+            # `not_installed` sits below this return. The `REFUSED` line in
+            # `verdict` therefore earns its place solely by outranking
+            # `UNKNOWN_INSTALLED`, which is what this branch now produces — and
+            # that is the ordering the refusal witness pins.
+            #
+            # Two sentences, both short of what an earlier draft said. That
+            # draft also reassured the reader that a live gate here "has not
+            # been shown to be withdrawn" and instructed them not to remove
+            # one — and a mutation deleting either clause left all 215 tests
+            # green, because nothing can witness a reassurance. The guarantee
+            # is carried by the status and by what these sentences do NOT say,
+            # both of which a test does hold: the operator is never sent to the
+            # projector from here.
+            if compiled&.refused?
+              return { status: 'unknown',
+                       detail: 'the declaration does not compile ' \
+                               "(#{compiled.record.dig('refusal', 'category')}), so what " \
+                               'this mode declares is undetermined and nothing installed ' \
+                               'can be compared against it',
+                       remedy: 'repair the declaration — the resolvable check above ' \
+                               'carries the reason' }
+            end
+
             wanted = compiled&.compiled? ? compiled.artifact['hooks'] : {}
             # The expected bytes come with the artifact: `files` maps each
             # config basename to the canonical JSON the projector writes

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kairos-chain
 version: !ruby/object:Gem::Version
-  version: 3.65.0
+  version: 3.66.0
 platform: ruby
 authors:
 - Masaomi Hatakeyama
@@ -601,6 +601,7 @@ files:
 - templates/skillsets/kairos_hook_projector/skillset.json
 - templates/skillsets/kairos_hook_projector/test/test_boot_time_assertion.rb
 - templates/skillsets/kairos_hook_projector/test/test_hooks_status.rb
+- templates/skillsets/kairos_hook_projector/test/test_mode_hooks_add.rb
 - templates/skillsets/kairos_hook_projector/test/test_mode_hooks_compiler.rb
 - templates/skillsets/kairos_hook_projector/test/test_mode_hooks_locator.rb
 - templates/skillsets/kairos_hook_projector/test/test_mode_hooks_project.rb
@@ -609,6 +610,7 @@ files:
 - templates/skillsets/kairos_hook_projector/test/test_readable_gate.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
 - templates/skillsets/kairos_hook_projector/tools/mode_hooks_project.rb
 - templates/skillsets/kairos_hook_projector/tools/mode_hooks_validate.rb
 - templates/skillsets/knowledge_creator/config/knowledge_creator.yml