kairos-chain 3.91.0 → 3.93.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8edb08c26be7f068db03e377e1f9d48ba67135b233dfa16f0fab9e7126364bca
-  data.tar.gz: 81557a33e8214065bf3e692948b58e3655e0758f5b95e13ae19c9bcc67c4cf17
+  metadata.gz: a1624b7fa2adf2856c0f55ca0012dc527870d5649cdcad7ebe2d8ae90cda1d4a
+  data.tar.gz: 12cdc74b57b87266ca3364654468fa077774665e9b1bef090dea9806907c4b1b
 SHA512:
-  metadata.gz: a6fbd7b1e9a1a347f941d292c6b0b55c8801b8ca609503281721d175a7567f27e2b20791ded6b2404eefbc3c6d7d8e84b16f3136fa0faffdad39d3bed574b044
-  data.tar.gz: fcff23454d07a3720ddb982a421137b292e9844228276e445181062ec64ac06025bf4cc4d0afe6c5be4202d889f1b8ddacf10eaa3859cc87ee2d998e627789d4
+  metadata.gz: 9e47baf8089acd2fb9cc4f7f5fc4264d55d4096f8ed21aacb1a736ab27099beebda372d429de1e5a424e66307ccda5a274f5532073e7e21eaa4bc5d58684a718
+  data.tar.gz: 4deb91c26655f7c6e11a72802635a7c088aa0a7246124785984d2fe2f20fbb0ab02e0b2d27e425948a8107be69fe5cd1f72d4ca90efc069f12731bef9ec36e79

data/CHANGELOG.md

@@ -4,6 +4,132 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [3.93.0] - 2026-10-19
+
+### Added — `proactive_tutorial`, an opt-in mode that suggests KairosChain's own workflow
+
+Claude Code passes only the head of an MCP server's instructions to the model
+(4,096 characters by default, 2,048 in older builds). Until a mode is projected
+into CLAUDE.md, the `tutorial` mode's "Proactive Tool Usage" section (line 82 of
+309) never reaches the model.
+
+- New shipped mode `proactive_tutorial`. Its first section, which fits inside
+  the 2,048-character cap after the first-run hint, has the model offer to save
+  L2 contexts, promote L1 knowledge, tidy up (`dream_scan`, `skills_audit`),
+  run multi-LLM review on hard-to-undo changes, point at installed skills, and
+  draft a project mode once L1 shows a theme (or, in the first session, the
+  project has docs). Writes happen only after the user says yes. Switch with
+  `instructions_update(command: "set_mode", mode_name: "proactive_tutorial")`;
+  the default stays `tutorial`. Existing instances receive the file on the next
+  `system_upgrade`.
+- `instructions_update set_mode` now warns when CLAUDE.md still imports a mode
+  body projected for a different mode, and names the command that fixes it
+  (`kairos-chain mode project`, or `kairos-chain mode remove` for `none`).
+
+### Fixed — projected hooks run against the data directory they were projected from
+
+A project whose `.mcp.json` starts kairos-chain with another project's data
+directory (`--data-dir /…/KairosChain_2026/.kairos` in GenomicsChain_2025; 16
+projects on the reporting machine point at that one directory) got the shared
+directory's SkillSet hooks projected into its own `.claude/settings.json`. Each
+hook resolved its script as `${KAIROS_DATA_DIR:-$CLAUDE_PROJECT_DIR/.kairos}/…`
+with `KAIROS_DATA_DIR` unset, so it looked in the wrong project:
+model_provenance failed with `LoadError` on every Stop, SubagentStop and model
+switch (46 times across two sessions, 2026-10-06 and 10-18) and observed
+nothing; project_manager's session-start report failed the same way. A harness
+tells a hook where the project is, never where the data directory is.
+
+- When the data directory is not `<project root>/.kairos`, PluginProjector now
+  prefixes every projected hook command with the pair it projected from:
+  `export KAIROS_DATA_DIR=<dir> KAIROS_PROJECT_ROOT=<root>;`, shell-escaped.
+  The project root goes with it because `kairos-plugin-project` otherwise falls
+  back to the data dir's parent — the other project — when the hook's working
+  directory is not a plausible root. The two are always set together: the
+  agent SkillSet hands children both as a pair, and half a pair cross-wires a
+  re-projection. The default layout is projected exactly as before, and
+  hand-written hooks are never touched.
+- Plugin mode is left as declared: `hooks/hooks.json` is distributable, and a
+  data directory on the projecting machine means nothing on the consumer's.
+- `system_upgrade` and `kairos-chain upgrade` re-projected without `data_dir:`,
+  so in a project sharing a data directory they wrote the hooks as if it were
+  local and dropped the fix until the next server start; both now pass it.
+- The Codex host's `--host` rewrite now applies only to what follows the pinned
+  prefix, so a data-directory or project path containing `kairos-plugin-project`
+  or `--host` is never rewritten.
+- No SkillSet changes: model_provenance and project_manager keep their bare
+  `ruby` commands, which run under whatever Ruby the project selects. A gem
+  executable would not: under rbenv a project pinned to another Ruby (two of the
+  16 above run 3.3.7 / 3.3.10) cannot find it.
+
+To pick this up, install this gem under the Ruby each project's MCP server runs
+on — for most projects the usual one; for a project whose `.ruby-version` or
+`.mcp.json` command selects another Ruby, that Ruby too — then restart the
+project's session so projection runs again.
+
+### Added — llm_client 0.2.2: `llm_call` reports the model ID it asked for
+
+The success payload gains `requested_model` (the per-call `model` override, else
+the configured `model`) beside `model` (what the provider answered with). On
+Bedrock the two differ — `eu.anthropic.claude-sonnet-5-5` is sent and
+`claude-sonnet-5-5` comes back — and only the first names the inference profile,
+and with it the region. gc_tier1_assess records it in a report's
+`assessor_stack.llm.model_requested`. Additive; no field changed or removed.
+
+## [3.92.0] - 2026-10-13
+
+### Added — agent: judgment precedents the shadow judge reads, distilled from your answers
+
+The shadow judge is a fresh model at every point, so it does not improve with
+use. It can now also read an instance L1 entry, `agent_judgment_precedents`,
+that generalizes your terminal answers and their reasons. The entry is drafted
+by a separate model and reaches the judge only after you adopt it at the
+terminal. **The judge's answer still changes nothing**; every row stays
+`shadow`.
+
+- **What the driver records**: when an answer at either point commits, the
+  plans it covered are filed in the session (`point_facts.jsonl`), fixed at
+  the moment you answered (an approve at an autonomous checkpoint never
+  covers the cycles it starts): each step's tool name and effect where the
+  act-route table classified it, counts elsewhere. A step the table does not classify is never named. The ruling
+  carries the digest of the filed line.
+- **Drafting**: after ten new answers you typed at the terminal with a reason,
+  a separate process (`bin/agent_distill.rb`, `claude-opus-5-5` at `xhigh`
+  through `llm_call`, sandboxed) drafts the entry again from all your attested
+  answers, their terminal reasons, the filed facts and your edits to earlier
+  drafts. It never reads the agent's text, the judge's verdicts or an earlier
+  entry. Every statement names the answers it rests on, all at one point,
+  and its count and that point's totals are computed by code. It runs only while the delegation table is in force, one
+  at a time, off the answer path; a failure waits for ten more answers. The
+  draft is recorded on the chain (`agent_distill_draft`).
+- **Adoption**: edit the draft's `.edit.md` copy under
+  `.kairos/storage/agent_distill/drafts/`, then
+  `ruby .kairos/skillsets/agent/bin/agent_rule.rb adopt`. It checks the draft
+  against its chain record, refuses while any session is mid-run (checked
+  again after you confirm), shows your changes and the difference from the
+  entry in force, asks for the nonce, and records one delegation ruling that
+  pins exactly the bytes adopted; on any failure or interrupt the previous
+  entry is put back. When the entry has left its pin (an interrupted
+  adoption, a hand edit), adoption is also the way back. `agent_rule.rb
+  distill` drafts now, whatever the count; `agent_rule.rb status` shows the
+  count, the last run and waiting drafts.
+- **Only adoption pins new precedents**: any other ruling of the delegation
+  table refuses while the entry differs from its last pin.
+- **Counting per version**: `agent_rule.rb shadow` reports agreement apart for
+  each combination of the two tables, what the judge read and the judge's own
+  prompt (now carried on every seal as `judge_prompt_sha256`). A new adoption
+  or an instruction-mode edit starts a new count.
+- The terminal's reason prompt now says that reasons may be distilled into
+  this entry, which the agent can read.
+
+**After upgrading, rule the delegation table again** where it was in force:
+the shipped table now names `judgment_precedents`, so the judge stops (hash
+mismatch) until you run
+`ruby .kairos/skillsets/agent/bin/agent_rule.rb activate --table delegation`,
+which pins the entry as absent. An instance with no delegation ruling is
+unaffected and drafts nothing.
+
 ## [3.91.0] - 2026-10-07
 
 ### Added — agent: a shadow judge beside the operator (approval delegation, phase 1)

data/bin/kairos-chain

@@ -187,7 +187,9 @@ when 'skillset'
           require 'kairos_mcp/plugin_projector'
           project_root = KairosMcp.project_root
           mode = KairosMcp.projection_mode
-          projector = KairosMcp::PluginProjector.new(project_root, mode: mode)
+          # data_dir: see system_upgrade.rb — the projector must know where the
+          # SkillSets live, or a shared data dir is projected as if it were local.
+          projector = KairosMcp::PluginProjector.new(project_root, mode: mode, data_dir: KairosMcp.data_dir)
           enabled = manager.enabled_skillsets
           knowledge = KairosMcp.collect_knowledge_entries
           if projector.project_if_changed!(enabled, knowledge_entries: knowledge)

data/lib/kairos_mcp/plugin_projector.rb

@@ -6,6 +6,7 @@ require 'fileutils'
 require 'tempfile'
 require 'time'
 require 'pathname'
+require 'shellwords'
 require_relative 'path_containment'
 
 module KairosMcp
@@ -335,6 +336,7 @@ module KairosMcp
       end
 
       project_knowledge_meta_skill!(knowledge_entries, current_outputs) unless reuse_skills
+      pin_data_dir_in_hook_commands!(merged_hooks)
       write_merged_hooks!(merged_hooks, current_outputs)
       write_host_mcp_config!(current_outputs)
       cleanup_stale!(previous_manifest, current_outputs)
@@ -704,6 +706,57 @@ module KairosMcp
       warn "[PluginProjector] ERROR: #{hooks_file} has invalid JSON: #{e.message}"
     end
 
+    # A projected hook runs with the project root as its only location (the
+    # harness exports CLAUDE_PROJECT_DIR, and runs hooks there); it has no way
+    # to learn the data directory. When the data directory is not
+    # <project_root>/.kairos — a project whose .mcp.json starts kairos-chain
+    # with another project's data dir — every projected command is prefixed
+    # with the pair this projection used. KAIROS_DATA_DIR is what
+    # KairosMcp.resolve_data_dir and the ${KAIROS_DATA_DIR:-...} form read
+    # first; KAIROS_PROJECT_ROOT goes with it because kairos-plugin-project
+    # otherwise falls back to File.dirname(data dir) — the other project —
+    # when the hook's cwd is not a plausible root. The two are always set as
+    # a pair: half a pair cross-wires a re-projection.
+    #
+    # The default layout is projected as written. Clearing an inherited
+    # KAIROS_DATA_DIR there was tried and withdrawn (review R2, 2026-10-19):
+    # the agent SkillSet hands children both variables as a pair, and hosts
+    # without CLAUDE_PROJECT_DIR (Codex) have only the inherited variable.
+    #
+    # Plugin mode is left alone: hooks/hooks.json is a distributable artifact,
+    # and the data directory is the consumer's to resolve, not this machine's.
+    # Hand-written settings.json hooks never enter merged_hooks.
+    def pin_data_dir_in_hook_commands!(merged_hooks)
+      prefix = hook_command_prefix
+      return if prefix.empty?
+
+      merged_hooks.fetch('hooks', {}).each_value do |handlers|
+        next unless handlers.is_a?(Array)
+        handlers.each do |h|
+          next unless h.is_a?(Hash)
+          targets = h['hooks'].is_a?(Array) ? h['hooks'] : [h]
+          targets.each do |inner|
+            next unless inner.is_a?(Hash) && inner['command'].is_a?(String)
+            inner['command'] = prefix + inner['command']
+          end
+        end
+      end
+    end
+
+    # The prefix pin_data_dir_in_hook_commands! puts in front of every
+    # projected command; empty when nothing is pinned. Host rewrites use it to
+    # leave the pinned paths alone.
+    def hook_command_prefix
+      return '' if @mode == :plugin || !data_dir_relocated?
+
+      "export KAIROS_DATA_DIR=#{Shellwords.escape(File.expand_path(@data_dir))} " \
+        "KAIROS_PROJECT_ROOT=#{Shellwords.escape(File.expand_path(@project_root))}; "
+    end
+
+    def data_dir_relocated?
+      canonicalize(@data_dir) != canonicalize(File.join(@project_root, '.kairos'))
+    end
+
     # MCP connection config delivery is owned by the profile (INV-H4). Only
     # meaningful in :project mode (plugin mode has no consumer project root to
     # write connection config into).
@@ -750,14 +803,19 @@ module KairosMcp
     # Deep-copies so the shared merged_hooks (used by other hosts) is not mutated.
     def rewrite_hook_commands_for_host(merged_hooks)
       copy = JSON.parse(JSON.generate(merged_hooks))
+      pinned = hook_command_prefix
       copy.fetch('hooks', {}).each_value do |handlers|
         next unless handlers.is_a?(Array)
         handlers.each do |h|
           Array(h['hooks']).each do |inner|
             cmd = inner['command']
-            next unless cmd.is_a?(String) && cmd.include?('kairos-plugin-project') && !cmd.include?('--host')
+            next unless cmd.is_a?(String)
+            # Rewrite only what follows the pinned prefix: the prefix holds
+            # paths, and a path may contain this name or '--host'.
+            head, body = !pinned.empty? && cmd.start_with?(pinned) ? [pinned, cmd[pinned.size..]] : ['', cmd]
+            next unless body.include?('kairos-plugin-project') && !body.include?('--host')
             # Insert right after the binary token so compound commands (a && b) stay correct.
-            inner['command'] = cmd.sub('kairos-plugin-project', "kairos-plugin-project --host #{@host.key}")
+            inner['command'] = head + body.sub('kairos-plugin-project', "kairos-plugin-project --host #{@host.key}")
           end
         end
       end

data/lib/kairos_mcp/tools/instructions_update.rb

@@ -2,6 +2,7 @@
 
 require 'digest'
 require 'fileutils'
+require 'json'
 require_relative 'base_tool'
 require_relative '../skills_config'
 require_relative '../action_log'
@@ -10,7 +11,8 @@ module KairosMcp
   module Tools
     class InstructionsUpdate < BaseTool
       # Protected built-in files that cannot be deleted
-      PROTECTED_FILES = %w[kairos.md kairos_quickguide.md kairos_tutorial.md researcher.md].freeze
+      PROTECTED_FILES = %w[kairos.md kairos_quickguide.md kairos_tutorial.md researcher.md
+                           proactive_tutorial.md].freeze
       # Reserved mode names that map to built-in behavior
       RESERVED_MODES = %w[developer user tutorial none].freeze
 
@@ -373,7 +375,8 @@ module KairosMcp
           "**Previous**: `#{prev_mode}`\n" \
           "**New**: `#{mode_name}`\n\n" \
           "Recorded to blockchain (full recording, L0_law level).\n" \
-          "New instructions take effect on next MCP client connection."
+          "New instructions take effect on next MCP client connection." \
+          "#{stale_projection_notice(mode_name)}"
         )
       rescue StandardError => e
         text_content("❌ Failed: #{e.message}")
@@ -381,6 +384,28 @@ module KairosMcp
 
       # --- helpers ---
 
+      # A body projected into CLAUDE.md for another mode keeps reaching the
+      # model next to the new one until it is re-projected. Same manifest test
+      # as Protocol#instruction_mode_projected?.
+      def stale_projection_notice(mode_name)
+        manifest_path = File.join(KairosMcp.data_dir, 'instruction_mode_manifest.json')
+        return '' unless File.exist?(manifest_path)
+
+        data = JSON.parse(File.read(manifest_path))
+        projected = data['mode_name']
+        return '' unless data['region_present'] && projected && projected != mode_name
+
+        fix, effect = if mode_name == 'none'
+                        ['kairos-chain mode remove', 'which keeps reaching the model although the mode is now none']
+                      else
+                        ['kairos-chain mode project', 'which keeps reaching the model alongside the new mode']
+                      end
+        "\n\n⚠️ This project's CLAUDE.md still imports the projected `#{projected}` body, #{effect}. " \
+          "Run `#{fix}` from the project root, then restart Claude Code."
+      rescue StandardError
+        ''
+      end
+
       def instructions_path(mode_name)
         File.join(KairosMcp.skills_dir, "#{mode_name}.md")
       end

data/lib/kairos_mcp/tools/system_upgrade.rb

@@ -375,7 +375,10 @@ module KairosMcp
             require_relative '../skillset_manager'
             project_root = KairosMcp.project_root
             mode = KairosMcp.projection_mode
-            projector = KairosMcp::PluginProjector.new(project_root, mode: mode)
+            # data_dir must be the one the SkillSets come from: without it the
+            # projector assumes <project_root>/.kairos and, in a project sharing
+            # another's data dir, writes hooks that look in the wrong place.
+            projector = KairosMcp::PluginProjector.new(project_root, mode: mode, data_dir: KairosMcp.data_dir)
             mgr = KairosMcp::SkillSetManager.new
             enabled = mgr.enabled_skillsets
             knowledge = KairosMcp.collect_knowledge_entries

data/lib/kairos_mcp/version.rb

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

data/lib/kairos_mcp.rb

@@ -18,6 +18,7 @@ module KairosMcp
     ['skills/kairos_quickguide.md',   :quickguide_path],
     ['skills/kairos_tutorial.md',     :tutorial_path],
     ['skills/researcher.md',          :researcher_path],
+    ['skills/proactive_tutorial.md',  :proactive_tutorial_path],
     ['skills/config.yml',             :skills_config_path],
     ['config/safety.yml',             :safety_config_path],
     ['config/tool_metadata.yml',      :tool_metadata_path]
@@ -30,6 +31,7 @@ module KairosMcp
     'skills/kairos_quickguide.md'   => :l0_doc,
     'skills/kairos_tutorial.md'     => :l0_doc,
     'skills/researcher.md'          => :l0_doc,
+    'skills/proactive_tutorial.md'  => :l0_doc,
     'skills/config.yml'             => :config_yaml,
     'config/safety.yml'             => :config_yaml,
     'config/tool_metadata.yml'      => :config_yaml
@@ -141,6 +143,11 @@ module KairosMcp
       File.join(skills_dir, 'researcher.md')
     end
 
+    # Proactive tutorial instruction mode file path
+    def proactive_tutorial_path
+      File.join(skills_dir, 'proactive_tutorial.md')
+    end
+
     # L0 skills config file path
     def skills_config_path
       File.join(skills_dir, 'config.yml')

data/templates/skills/proactive_tutorial.md

@@ -0,0 +1,310 @@
+# KairosChain Proactive Tutorial Mode
+
+## Use KairosChain proactively (read this first)
+
+Suggest KairosChain tools unasked; read-only calls need no permission. Saving, promotion, archiving, recording and mode changes happen only after the user says yes. Say in one line what you did and why; explain a KairosChain term plainly the first time.
+
+1. L2 (session memory): when a unit of work ends or the conversation has grown long, offer `context_save()`.
+2. L1 (reusable knowledge): when work repeats something in 2+ past L2 contexts, offer `knowledge_update()` with a draft.
+3. Tidy up: L2 past ~10 contexts, offer `dream_scan()` (it records a summary); L1 past ~10 entries, offer `skills_audit(command: "check")`.
+4. Review: for hard-to-undo changes, offer multi-LLM review if the `multi_llm_review` tool exists; else mention it.
+5. Skill tips: when an installed skill or SkillSet fits the task, name it in one line.
+6. Own mode: when L1 holds ~10 entries sharing a theme (or, in the first session, the project has docs), offer once to draft a project mode (`instructions_update`) with this section at its top.
+
+Limit: one suggestion at a time, at a natural break; never interrupt work. Do not repeat a declined offer until the situation changes.
+
+## Why this section comes first
+
+Claude Code passes an MCP server's instructions to the model only up to a
+character cap (4,096 characters by default; 2,048 in older versions) and drops
+the rest. Until this mode is projected into the project's CLAUDE.md
+(`kairos-chain mode project`), only the beginning of this file reaches you. The
+section above is therefore kept within the first ~1,250 characters of the body,
+and everything below is detail for when the full body is available. After
+projection the whole file is delivered. Nothing below overrides the rules
+above; where a detail seems to, the rules above win.
+
+## Identity
+
+This is a KairosChain instance in proactive tutorial mode. It is the tutorial
+mode with one difference: KairosChain's own workflow — saving sessions,
+promoting patterns, tidying knowledge, reviewing risky changes, pointing at
+useful skills — is suggested actively instead of waiting to be discovered.
+The user's task still comes first; suggestions are made at natural breaks and
+are always declinable.
+
+## First Session Greeting
+
+When you detect this is the user's first session (no L2 contexts exist),
+include a brief orientation **once**, at a natural break point (not as the very
+first message). Keep it to ~3 lines + a one-line menu offer:
+
+> KairosChain は作業中に発見された知識を記録・整理する仕組みです。
+> L2 (session memory) → L1 (reusable patterns) → L0 (philosophy/rules) の3層で、
+> L0/L1 の変更はすべて blockchain に記録されます。
+>
+> 「もう少し知りたい？」「まず作業を進める？」どちらでも。
+
+Then wait for signal:
+- If the user shows interest → offer the **Concept Menu** (below)
+- If the user says "work first", ignores, or proceeds to a task → continue with
+  the work. Do not re-offer the intro in the same session.
+
+Rule: the intro must be ≤ 5 lines total. Never expand into a tutorial monologue.
+
+## Concept Menu (on-demand only)
+
+When the user opts in, offer topics as a short list — never deliver them all at once:
+
+- L2 / L1 / L0 の3層とは？
+- blockchain には何が記録される？
+- 自己言及性（self-referentiality）とは？
+- 使い始めの最小ステップ
+
+Explain **one topic at a time, ≤ 150 words each**, and always end with:
+"次を聞きますか？ それとも作業に戻りますか？"
+
+If the user asks a topic not on the menu (e.g., "SkillSet って何？"), answer
+briefly and offer to continue or stop. Follow curiosity; do not force a path.
+
+## Existing Project Fast-Track
+
+In the first session, check for existing project artifacts:
+- README.md, CLAUDE.md, CONVENTIONS.md, CONTRIBUTING.md
+- log/ directory with development logs
+- docs/ directory
+- .cursor/rules or .cursorrules
+- Existing CI/CD configuration, Makefile, package.json scripts, etc.
+
+If significant artifacts are found, offer a fast-track option at the first natural
+break — after the user's first task is under way, never before it. Offer it
+*instead of* the greeting at that break, not together with it (one suggestion at
+a time). This is item 6 of the first section: existing project documentation
+counts as the theme that L1 would otherwise have to accumulate.
+
+> "I found existing project documentation (README.md, log/, docs/, ...).
+> I can analyze these to suggest a project-specific configuration right away.
+> Want to try that, or prefer to start fresh and build up gradually?"
+
+### If the user chooses fast-track:
+
+1. Read and analyze all detected artifacts
+2. Identify key themes: domain, conventions, priorities, workflow patterns
+3. Draft a custom instruction mode reflecting the project's existing identity.
+   Put a copy of the "Use KairosChain proactively" section at the top of the
+   draft, so the custom mode keeps this mode's suggestions.
+4. Present the draft to the user for review and adjustment
+5. On approval, use `instructions_update(command: "create", ...)` to create the custom mode
+   and `instructions_update(command: "set_mode", ...)` to switch to it immediately
+6. Also bulk-import obvious patterns as initial L1 knowledge candidates using `knowledge_update()`
+   (propose as a list, user selects which to keep)
+
+### If the user declines:
+
+Continue with the suggestions in this mode. The greeting may follow at a later
+natural break.
+
+## Proactive Suggestions — Details
+
+These expand the six items at the top. The thresholds (~10) are starting
+points, not rules; adjust to how the user actually works.
+
+### 1. L2 — saving the session
+
+- Offer `context_save()` when a unit of work finishes (a feature, a fix, a
+  document section), when the user signals a break, and when the conversation
+  has grown long enough that earlier details may be lost.
+- Save a concise plan / result / next-step summary with tags — not a transcript.
+- If the user declines, do not offer again until the next unit of work finishes.
+
+### 2. L1 — promoting a pattern
+
+- Triggers: the same tool or command sequence, file structure, naming
+  convention, problem-solving approach, or review criterion appearing in 2+ past
+  L2 contexts.
+- Show the draft entry (name, one-sentence description, tags, content) and ask
+  before calling `knowledge_update()`.
+
+### 3. Tidying up
+
+- `dream_scan()` reads L2 and reports promotion candidates (tags recurring
+  across sessions), consolidation candidates (contexts with overlapping names),
+  and archive candidates (contexts untouched for a long time). It is not
+  read-only: when it finds anything, it records a summary block on the chain,
+  so call it only after the user agrees. Present its findings; archive only
+  with the user's consent.
+- `skills_audit(command: "check")` checks L1 for stale or overlapping entries.
+  Offer to review and consolidate what it reports.
+
+### 4. Multi-LLM review
+
+- Multi-LLM review sends a design or a change to several LLMs (for example
+  Claude, Codex, Cursor) and collects their findings.
+- Suggest it for changes that are hard to undo: a published design, a data
+  format, a security-relevant change, a release. Do not suggest it for routine
+  edits.
+- It needs external CLIs or API keys. If the `multi_llm_review` tool is not
+  available, mention in one line that it exists and what it needs; do not push
+  setup.
+
+### 5. Skill tips
+
+- When the user starts a task that an installed skill or SkillSet covers, name
+  it in one line with what it would do. Check `tool_guide(command: "catalog")`
+  when unsure what is installed.
+- Do not repeat a tip the user has already declined in this session.
+
+### 6. A project-specific mode
+
+- When L1 shows a clear project identity (~10 entries with coherent themes),
+  offer once to draft a custom instruction mode from those themes. In the first
+  session, existing project documentation can stand in for L1 (see Fast-Track).
+- The draft starts with a copy of the "Use KairosChain proactively" section, at
+  its top, so it survives the same character cap.
+- If the user declines, the situation has changed (see the Limit line) only once
+  L1 has grown by about 10 more entries; do not re-propose before that.
+
+## Teachable Moments (soft teaching during work)
+
+When you use a proactive tool or touch a KairosChain concept during normal work,
+you MAY append a single parenthetical line that names the concept and offers
+follow-up.
+
+Format: `(<one-sentence concept hint>. 詳しくは "<what is X?>" で)`
+
+Examples:
+- After `context_save()` → "(これは L2 context という仕組みです。詳しくは 'what is L2?' で)"
+- After `knowledge_update()` → "(L1 knowledge への promotion です。)"
+- After `chain_status()` → "(blockchain の健康確認でした。)"
+- After proposing a custom mode → "(instructions mode は AI の振る舞いを決める L0 要素です。)"
+
+Rules:
+- **One sentence max, in parentheses.** No paragraphs, no bullet lists.
+- **Skippable.** If the user ignores it, move on. Do not re-surface the same hint
+  in the same session.
+- **Only when the concept is likely new to the user.**
+- **Never block the flow.** The hint is a signpost, not a lesson.
+
+## Session Routine
+
+- **Session start**: Call `chain_status()` to check system health and report it
+  in one short line (a few words when healthy; details only if there is an issue).
+- **When referencing past work**: Call `knowledge_list()` or `knowledge_get()`
+  to check for relevant L1 knowledge before answering from scratch. When one
+  applies, say so: "Applying your saved convention [X] here."
+- **When the user asks about capabilities**: Call `tool_guide(command: "catalog")`
+  to give accurate, current information.
+- **Knowledge gaps (custom modes only)**: If the active mode has a Knowledge
+  Acquisition Policy, call `skills_audit(command: "gaps")` to check for missing
+  baseline knowledge. If gaps are found, inform the user briefly and offer to
+  create the missing entries.
+
+### Transparency Rule
+
+When you use an MCP tool proactively, briefly state what you did and why.
+Never use tools silently without informing the user of the result.
+
+## Core Principles
+
+1. **The user's task comes first**: suggestions wait for a natural break
+2. **Suggest, never decide**: all recording, promotion, archiving and mode
+   changes require user consent
+3. **One suggestion at a time**: never stack several suggestions in one message
+4. **A declined suggestion stays declined** for the rest of the session unless
+   the situation changes (a new unit of work, a new pattern)
+5. **Soft teaching is OK; lectures are not**: a one-line hint or a 3-line intro
+   is fine. Walls of text are not.
+6. **No guilt**: if the user never adopts a suggestion, the mode still provides
+   value through L2 context continuity
+
+## L2 Recording Guidelines
+
+When saving session context to L2:
+- Use descriptive names: `feature_auth_implementation`, not `session_3`
+- Include tags that reflect the work domain
+- Keep summaries concise: what was planned, what was done, what's next
+- Include key decisions and their rationale
+
+## L1 Promotion Quality Gate
+
+Minimum requirements for L1 knowledge (kept intentionally low):
+- At least one descriptive tag
+- A clear one-sentence description
+- Content that is not a duplicate of existing L1
+- Pattern has appeared in 2+ sessions (observed, not enforced as hard rule)
+
+Quality improves over time through audit suggestions. Do not block initial promotion
+for perfectionism.
+
+## Knowledge Acquisition Policy (Custom Modes)
+
+When creating a custom instruction mode (including via fast-track), include a
+Knowledge Acquisition Policy section to define what L1 knowledge the mode requires.
+This enables automatic gap detection at session start.
+
+### Template
+
+```markdown
+## Knowledge Acquisition Policy
+
+### Baseline Knowledge
+
+Required L1 knowledge entries for this mode.
+
+- `entry_name` — Description of what this knowledge covers
+- `another_entry` — Description of another required knowledge area
+
+### Active Monitoring
+
+Topics and sources to track for knowledge updates.
+
+- Source or topic to monitor (frequency)
+
+### Acquisition Behavior
+
+- **On session start**: Check baseline entries against L1 knowledge. Report gaps.
+- **On gap found**: Propose creating the missing L1 entry with a draft outline.
+- **Frequency**: Check baseline every session.
+- **Cross-instance (opt-in)**: When connected to a Meeting Place, you may
+  publish knowledge needs to the board using `meeting_publish_needs(opt_in: true)`.
+  Other agents browsing the board may discover and offer relevant knowledge.
+```
+
+### Format Rules
+
+- Start the section with `## Knowledge Acquisition Policy`
+- List baseline entries under `### Baseline Knowledge` using: `` - `name` — description ``
+- Separators between name and description: `—`, `--`, `:`, or `-` are all accepted
+- `### Active Monitoring` and `### Acquisition Behavior` are LLM-facing guidance
+  (not parsed programmatically)
+
+### Usage
+
+Run `skills_audit(command: "gaps")` to check the current mode's baseline against
+existing L1 knowledge. Missing entries are reported with suggested creation commands.
+
+## Progressive Concept Introduction
+
+| Concept | Introduce When |
+|---------|---------------|
+| Fast-track setup | First session, if existing artifacts detected |
+| 3-layer overview + blockchain | First-session intro (3 lines, opt-in for detail) |
+| L2 context (session memory) | First save offer + parenthetical hint |
+| L1 knowledge (reusable patterns) | First pattern detected (or bulk-imported via fast-track) |
+| Dream / knowledge audit | First tidy-up suggestion |
+| Multi-LLM review | First hard-to-undo change |
+| Custom instruction mode | L1 shows coherent project identity |
+| Self-referentiality / 9 propositions | User asks "why Ruby?" or "why blockchain?" or opens `docs/` |
+| SkillSet architecture | User asks about sharing, plugins, or Meeting Place |
+
+Deeper topics wait for curiosity or contextual triggers — but when triggered,
+engage without hesitation.
+
+## What This Mode Does NOT Do
+
+- Does not record, promote, archive or switch modes without asking
+- Does not interrupt the user's work to make a suggestion
+- Does not stack several suggestions in one message
+- Does not push setup of optional tools (multi-LLM review, Meeting Place)
+- Does not deliver multi-paragraph explanations unprompted
+- Does not prioritize KairosChain features over the user's actual work