kairos-chain 3.52.1 → 3.55.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6bc15d467e1fbef211be82d39ec89bfdc760d7bdd67286635967c95c2acd2ce
-  data.tar.gz: b761078e7adc2798988a2fb0154bbbf998b37eed14d9979e87e7656194f03b76
+  metadata.gz: 2291c491a077a0cfdce3d77bdd3709e8e6278fc9eb656a02f3de5508e4f66580
+  data.tar.gz: 96fa06b0195df3167b3113c54125a093f31f4bed10955c044a2ef218fe6d9278
 SHA512:
-  metadata.gz: 604f315facca09bdb89e8abe403cf2873abe6a201cf9771181f04a813c323685da0749237e0f3f547379f9ce1dc7a8976b3e12f657c4718604ef694368f15f27
-  data.tar.gz: 67b55d37e2ba35259b1df7e42c96222cf637a9b295eac63b877b715f060310ff19841c2152de9fad1a92345a8f40738803b47a68b020e74ad9405c923a17de6b
+  metadata.gz: 72064bd0e1bde0516e8dd2b90adcbb9a85f3d079f71507b9f77210985e2f995fc9a1e8af066eee19835dda664a707f09ae8f6420ecfb6135dec62aa92449b756
+  data.tar.gz: 2553da41e8590b33c49f8e0d3526d37ac80bc8f742bab79af45cb5798c7a425ad978e66099a47454f9ca1ade3cbce310a798b7a9d1400eedac7a781d3cfdd745

data/CHANGELOG.md

@@ -4,6 +4,257 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.55.0] - 2026-07-27
+
+### Added
+
+- **`project_manager` SkillSet now ships with the gem** (v0.2.0). Previously
+  instance-local. Registers projects and work items, answers queries, produces a
+  session-start digest with derived dormancy, and records irreversible project
+  actions on the attestation chain. Ships a secretary-persona sub-agent under
+  `plugin/agents`, so the secretarial disposition runs in its own context under
+  any instruction mode rather than replacing the active one.
+- **`scripts/l2_scan.py`** — read-only derivation of activity evidence from the
+  L2 context store. Reports, per work item, first and last activity, distinct
+  records, distinct active days, the interval against the memo's own marker, and
+  the most recent nearby record by name. It matches on a document's name, saved
+  path and tags — never its body, which measured roughly 25% precision — and it
+  claims no attribution: tags name subjects while items name work that remains,
+  so one record sits correctly under several items and the output is evidence for
+  the operator to judge. Writes nothing.
+
+### Notes
+
+- The operator's own data (the work-item store and the item-to-record mapping)
+  stays instance-local under `.kairos/pm/` and is not part of the package.
+- Designs: `docs/drafts/project_manager_plugin_projection_draft_v0.7_FROZEN.md`
+  (sub-agent and confinement) and
+  `docs/drafts/project_manager_l2_derivation_draft_v0.12.md` (derivation).
+  Both state that the SkillSet stays instance-local; that is superseded by this
+  release on the operator's decision.
+
+## [3.54.3] - 2026-07-27
+
+### multi_llm_review SkillSet 0.5.2 — the cursor reviewer pins its model
+
+The cursor roster entry carried no `model` key, so `cursor_adapter` omitted
+`--model` and the reviewer ran on whatever the cursor CLI had as its default. That
+default lives in `~/.cursor/cli-config.json`, is operator-editable from the
+interactive Cursor client, and had been set to `claude-opus-4-8`.
+
+The roster was therefore dispatching three Anthropic slots out of five — the
+orchestrator's own persona team, Opus 4.6 via `claude -p`, and this entry — while
+still labelling this one `cursor_composer2.5`. Both properties the roster exists for
+were lost at once: provider diversity, which is the reason a five-model roster is
+worth its cost, and the correspondence between a recorded `role_label` and the model
+that actually answered, without which per-reviewer calibration accumulates against
+the wrong name. Neither failure is visible from the review output.
+
+The entry now names `composer-2.5` explicitly, which makes the roster independent of
+a setting that is not part of this repository. The comment above it records why the
+key is there, so a future edit does not remove it as redundant.
+
+Config files stay operator-owned: an instance whose roster is untouched picks the
+pinned model up on upgrade, and an instance that has already tuned its roster keeps
+its own and should apply the same pin by hand.
+
+- **`templates/skillsets/multi_llm_review/config/multi_llm_review.yml`**: cursor entry gains `model: composer-2.5`.
+- **`templates/skillsets/multi_llm_review/skillset.json`**: 0.5.1 → 0.5.2.
+
+## [3.54.2] - 2026-07-27
+
+### multi_llm_review SkillSet 0.5.1 — so 3.54.1's changes actually propagate
+
+3.54.1 shipped the roster change without bumping the SkillSet's own version, and
+`skillset upgrade` is gated strictly on `Gem::Version` comparison. An existing
+instance therefore reported `[UNCHANGED] multi_llm_review v0.5.0` and kept its
+`lib/` and `tools/` as they were — the shipped changes reached the gem and stopped
+there.
+
+Two things were stranded by that. The `orchestrator_model` description is the one
+that matters: it now states that the identifier must be passed as a bare ID with a
+context suffix such as `[1m]` stripped, because the roster comparison rejects the
+suffixed form and the caller then dispatches a subprocess against itself. That is
+a behavioural instruction an orchestrating model reads at call time, not a comment.
+The dispatcher's per-reviewer effort comment was stranded with it.
+
+Nothing about the fix is new content; this release exists so the previous one is
+deliverable. Config files stay operator-owned and are not replaced, so an instance
+that has already tuned its roster keeps it across the upgrade.
+
+- **`templates/skillsets/multi_llm_review/skillset.json`**: 0.5.0 → 0.5.1.
+
+Lesson recorded for future SkillSet edits: bumping the gem version is not enough.
+A change under `templates/skillsets/<name>/` reaches an existing instance only if
+that SkillSet's own `version` also moves.
+
+## [3.54.1] - 2026-07-27
+
+### Fable 5 retired from the multi-LLM review roster
+
+Five consecutive rounds returned nothing substantive from that slot: 85 to 128
+characters in 5 to 7 seconds, each an opening sentence with no findings and no
+verdict text. A slot that does not produce a review still counts toward the
+denominator, so it lowered the achievable numerator without contributing signal —
+with six configured reviewers and one permanently silent, `4/6` could not be
+reached even when every working reviewer approved.
+
+The roster is now five and the convergence rule is `3/5` (`3/4` after
+orchestrator exclusion), keeping the same `ceil(N * 0.6)` majority basis. One
+consequence is worth stating: with Opus 5 as orchestrator its own slot is
+delegated to the persona team, so the Claude CLI side is Opus 4.6 alone.
+
+Restoring the entry is a config edit plus widening the rule back to a six-reviewer
+basis; the retirement rationale is recorded inline where the roster lives.
+
+- **`templates/skillsets/multi_llm_review/config/multi_llm_review.yml`**: entry
+  removed, `convergence_rule` and `convergence_rule_after_exclusion` adjusted,
+  roster header and the orchestrator-exclusion example updated.
+- **`templates/knowledge/multi_llm_review_workflow/`**: identifier list, retirement
+  history, and the two-frontier-entry rationale corrected.
+
+Note for operators of an existing instance: `config/` files are operator-owned and
+are not replaced on upgrade, so an instance that already ran the six-reviewer
+roster keeps it until the config is edited by hand.
+
+## [3.54.0] - 2026-07-26
+
+### SkillSet-declared knowledge becomes reachable
+
+`knowledge_dirs` in `skillset.json` was a declaration nothing read. Knowledge
+bundled with a SkillSet was therefore write-only: present on disk, declared in
+the manifest, and unreachable by name. Two independent causes, either sufficient
+on its own — no core path consumed the field, and `add_external_dir` mutates a
+single provider instance during SkillSet load while `knowledge_get` builds a
+fresh provider per call, discarding the registration.
+
+Resolution moved from imperative load-time mutation to declarative manifest
+reading, which puts `knowledge_dirs` on the same footing as `tool_classes` and
+`config_files`: the manifest is what governs. On a representative instance this
+takes SkillSet-derived L1 entries from 0 to 23 across 16 SkillSets.
+
+- **`lib/kairos_mcp/knowledge_provider.rb`**: `#initialize` now registers the
+  knowledge directories of every *enabled* SkillSet. Opt out with
+  `include_skillset_knowledge: false` for a provider scoped strictly to the main
+  knowledge dir.
+- **`add_external_dir` gains `only:`**. The method takes a *container* of
+  entries, while `knowledge_dirs` declares *entry* directories; declared entries
+  are grouped by container and passed as `only:`. Without it, registering the
+  container would expose undeclared siblings — proximity on disk would become a
+  declaration. Knowledge a SkillSet ships without declaring stays invisible.
+- **`add_external_dir` is idempotent** by absolute path, so the five SkillSets
+  that also register themselves do not produce duplicate `list` entries.
+- **Failure is isolated**: a malformed `skillset.json` degrades to "no SkillSet
+  knowledge" with a warning on stderr, never to a broken knowledge layer.
+- **`templates/skillsets/hestia/skillset.json`**: declares
+  `knowledge/hestia_chain_migration`, which shipped undeclared since its
+  introduction — the only declared-vs-actual mismatch across all SkillSets, and
+  how the undeclared-knowledge case was found.
+- **`test_skillset_knowledge_registration.rb`** (new, 15 assertions): retrieval
+  by name, `list` source/layer tagging, disabled SkillSets contributing nothing,
+  opt-out, idempotency, undeclared siblings staying invisible, and survival of a
+  malformed manifest.
+
+### New L1 knowledge
+
+- **`kairoschain_development_pitfalls`**: failure modes that cannot be inferred
+  from reading the code being touched — the gem ships only `templates/`, so
+  entries under the dev-repo `knowledge/` reach nobody; `.kairos/` resolves
+  against the current working directory and silently creates a second data
+  directory on a wrong resolution; declared-but-undeclared knowledge; a truthy
+  return that is not a success (`PlaceRouter#authenticate!`); and an observed but
+  unexplained `instructions_mode` revert after upgrade.
+- **`instance_session_protocol`**: the procedural half of an instance's operating
+  discipline — session-start calls, layer-state surfacing, continuity, knowledge
+  baseline, during-work and session-end tool discipline. Extracted from the
+  `masa` instruction mode so norms stay in the mode and the runbook loads on
+  demand. Contains no normative content.
+- **`hestiachain_meeting_place`** gains § Interaction Policy: the outbound
+  redaction / inbound review / per-operation gate checklist, likewise extracted
+  from instruction-mode text.
+
+## [3.53.1] - 2026-07-25
+
+### Multi-LLM Review — Opus 5 enters the roster, Opus 4.8 retires (v3.6.2)
+
+Both frontier Claude models (Opus 5, Fable 5) now sit in the reviewer roster at
+once. This is not redundancy: whichever one is the session orchestrator matches
+`orchestrator_model` and is taken by the default `delegate` strategy as the
+persona-team slot, so the other is dispatched as a `claude -p` subprocess. The
+Claude side therefore resolves to "orchestrator persona + other frontier model
+via CLI + Opus 4.6 via CLI" under either orchestrator, with no per-orchestrator
+configuration branch and no dispatcher change.
+
+Opus 4.8 retires by the same succession logic that retired 4.7 in 3.51.2 (the
+strictness / systematizing register passes to the direct successor). Roster size
+stays 6, so `convergence_rule` (4/6) and `convergence_rule_after_exclusion`
+(3/5) are unchanged.
+
+- **`templates/skillsets/multi_llm_review/config/multi_llm_review.yml`**: roster
+  is now `claude-opus-5`, `claude-fable-5`, `claude-opus-4-6`, `gpt-5.6-sol`,
+  `gpt-5.5`, cursor default. The two frontier entries carry CLI-neutral
+  `role_label`s (`claude_cli_opus5`, `claude_cli_fable5`) because either can
+  take either path; the delegated one is relabelled `claude_team_<model>` by
+  PersonaAssembly at collect.
+- **`templates/skillsets/llm_client/lib/llm_client/claude_code_adapter.rb`**:
+  `DEFAULT_MODEL` `claude-opus-4-8` -> `claude-opus-5`. Fallback only — roster
+  entries always pass an explicit model; the constant exists so an unspecified
+  call cannot be auto-routed to Haiku.
+- **`templates/knowledge/multi_llm_review_workflow/` v3.6.1 -> v3.6.2**: roster,
+  CLI matrix, effort table, and orchestrator self-identification section updated
+  for the rotating-frontier arrangement.
+
+Two corrections folded into the same knowledge revision:
+
+- **`--bare` removed from every `claude -p` example.** The flag skips credential
+  loading, so the subprocess returns "Not logged in" (established 2026-07-23)
+  while the knowledge entry still mandated it. Project-instruction bias is
+  suppressed by `review_context: independent` instead.
+- **`orchestrator_model` must be the bare model ID.** Opus 5 reports itself as
+  `claude-opus-5[1m]`; the roster compares by exact string and PersonaAssembly's
+  validator rejects `[`, so passing the raw self-report silently defeats
+  self-exclusion and lets the orchestrator review its own output.
+
+Opus 5's reviewer bias profile is uncalibrated — record (a)/(b)/(c) breakdowns
+per round in `multi_llm_reviewer_evaluation` until a profile accumulates.
+
+No dispatcher, tool, or schema changes. Existing suite green (multi_llm_review
+skillset tests: 249 runs, 0 failures).
+
+## [3.53.0] - 2026-07-24
+
+### SkillSet Web Catalog — anonymous public presentation surface for SkillSet deposits
+
+Adds an anonymous, read-only web catalog for Meeting Place SkillSet deposits
+(including certified distillates), closing the presentation gap with the
+existing skill catalog: SkillSet deposits were previously reachable only
+through the authenticated agent API and had no browser-visible surface.
+
+Design `skillset_web_catalog` v0.3.1 FROZEN (design review 3 rounds, R3 6/6
+APPROVE unanimous; implementation review 3 rounds, R3 8/8 APPROVE unanimous).
+
+- **PlaceRouter public-route mechanism (WC-1/WC-2)**: extensions declare
+  unauthenticated `/place/web/` routes via `#public_route_prefixes` (the
+  capability travels with the extension, so every registration path wires it);
+  read-only by construction, dispatched through `#public_call` with no peer
+  identity; declarations are recorded and introspectable; the window
+  contributes method restriction, per-client rate limiting, and transport
+  security headers (CSP `default-src 'none'`, `X-Frame-Options: DENY`,
+  `nosniff`).
+- **skillset_exchange catalog (WC-3/WC-4/WC-5)**: anonymous `/place/web/skillsets`
+  listing + per-deposit detail views. Certificate summary is projected onto the
+  CD-2 checkability vocabulary at the deposit crossing (never on the anonymous
+  path); provenance is rendered as a co-equal field with three truthful states
+  and no ranking/badge/filter keyed on certificate presence (CD-3); depositor
+  text is structurally separated and HTML-escaped; per-deposit-instance
+  addresses sever withdrawn/replaced listings; `no-store` caching.
+- **docker/Caddyfile**: `header_up X-Real-IP {remote_host}` on the meeting-place
+  reverse-proxy blocks so the per-client rate limit keys on the real client and
+  cannot be spoofed or collapsed to the shared proxy IP.
+
+New test suite `test_skillset_web_catalog.rb` (68 assertions). Exchange
+interfaces, storage, and the hestia skill catalog are consumed unchanged.
+
 ## [3.51.3] - 2026-07-23
 
 ### Multi-LLM Review — knowledge template sync (v3.6.1)

data/lib/kairos_mcp/http_server.rb

@@ -374,10 +374,22 @@ module KairosMcp
           require_path = File.join(ss.path, ext_def['require'])
           require require_path
           ext_class = Object.const_get(ext_def['class'])
-          router.register_extension(
-            ext_class.new(router),
-            route_action_map: ext_def['route_actions'] || {}
-          )
+          # public_routes (skillset web catalog design WC-2): pass only when the
+          # installed hestia PlaceRouter supports it, so a newer gem composes
+          # with an older hestia SkillSet (and vice versa) without breaking.
+          supports_public = router.method(:register_extension).parameters.any? { |_type, name| name == :public_routes }
+          if supports_public
+            router.register_extension(
+              ext_class.new(router),
+              route_action_map: ext_def['route_actions'] || {},
+              public_routes: ext_def['public_routes'] || []
+            )
+          else
+            router.register_extension(
+              ext_class.new(router),
+              route_action_map: ext_def['route_actions'] || {}
+            )
+          end
         rescue StandardError => e
           $stderr.puts "[HttpServer] Failed to load extension '#{ext_def['class']}' " \
                        "from SkillSet '#{ss.name}': #{e.message}"

data/lib/kairos_mcp/knowledge_provider.rb

@@ -4,6 +4,7 @@ require 'digest'
 require 'fileutils'
 require 'yaml'
 require_relative 'anthropic_skill_parser'
+require_relative 'skillset_manager'
 require_relative 'kairos_chain/chain'
 require_relative 'vector_search/provider'
 require_relative '../kairos_mcp'
@@ -39,7 +40,11 @@ module KairosMcp
     # @param knowledge_dir [String] Path to knowledge directory
     # @param vector_search_enabled [Boolean] Enable vector search
     # @param storage_backend [Storage::Backend, nil] Storage backend to use
-    def initialize(knowledge_dir = nil, vector_search_enabled: true, storage_backend: nil, user_context: nil)
+    # @param include_skillset_knowledge [Boolean] Register knowledge dirs declared
+    #   by enabled SkillSets. Default true; pass false to build a provider scoped
+    #   strictly to the main knowledge dir.
+    def initialize(knowledge_dir = nil, vector_search_enabled: true, storage_backend: nil,
+                   user_context: nil, include_skillset_knowledge: true)
       knowledge_dir ||= KairosMcp.knowledge_dir(user_context: user_context)
       @knowledge_dir = knowledge_dir
       @user_context = user_context
@@ -49,19 +54,34 @@ module KairosMcp
       @index_built = false
       @external_dirs = []
       FileUtils.mkdir_p(@knowledge_dir)
+      register_skillset_knowledge_dirs if include_skillset_knowledge
     end
 
     # Register an external knowledge directory (e.g. from a SkillSet)
     # Knowledge is read-only from external dirs; no merge into the main dir.
     #
-    # @param dir [String] Absolute path to the knowledge directory
+    # @param dir [String] Absolute path to the container directory holding entry
+    #   subdirectories (e.g. `<skillset>/knowledge`), not an entry directory itself
     # @param source [String] Identifier for the source (e.g. "skillset:mmp")
     # @param layer [Symbol] Layer governance (:L0, :L1, :L2)
     # @param index [Boolean] Whether to include in vector search index
-    def add_external_dir(dir, source:, layer: :L1, index: true)
+    # @param only [Array<String>, nil] Entry names to expose. nil exposes every
+    #   subdirectory. Passing the declared set keeps undeclared knowledge shipped
+    #   inside a SkillSet from becoming visible as L1 by proximity alone.
+    #
+    # Idempotent by directory: registering the same dir twice (e.g. once from the
+    # SkillSet manifest at construction, once from a SkillSet that also registers
+    # itself) keeps the first registration rather than duplicating list entries.
+    def add_external_dir(dir, source:, layer: :L1, index: true, only: nil)
       return unless File.directory?(dir)
 
-      @external_dirs << { dir: dir, source: source, layer: layer, index: index }
+      absolute = File.expand_path(dir)
+      return if @external_dirs.any? { |ext| ext[:dir] == absolute }
+
+      @external_dirs << {
+        dir: absolute, source: source, layer: layer, index: index,
+        only: only && Array(only).map { |n| File.basename(n.to_s) }
+      }
       @index_built = false if index # Invalidate index when new indexed dir added
     end
 
@@ -92,7 +112,7 @@ module KairosMcp
 
       # Include knowledge from external directories (SkillSets)
       @external_dirs.each do |ext|
-        external_skill_dirs(ext[:dir]).each do |dir|
+        external_skill_dirs(ext[:dir], only: ext[:only]).each do |dir|
           skill = AnthropicSkillParser.parse(dir)
           next unless skill
 
@@ -124,6 +144,8 @@ module KairosMcp
 
       # Search external directories
       @external_dirs.each do |ext|
+        next if ext[:only] && !ext[:only].include?(name)
+
         ext_skill_dir = File.join(ext[:dir], name)
         return AnthropicSkillParser.parse(ext_skill_dir) if File.directory?(ext_skill_dir)
       end
@@ -327,7 +349,7 @@ module KairosMcp
 
       # Include external dirs that have indexing enabled
       @external_dirs.select { |ext| ext[:index] }.each do |ext|
-        external_skill_dirs(ext[:dir]).each do |dir|
+        external_skill_dirs(ext[:dir], only: ext[:only]).each do |dir|
           skill = AnthropicSkillParser.parse(dir)
           next unless skill
 
@@ -523,6 +545,43 @@ module KairosMcp
 
     private
 
+    # Register the knowledge directories declared by every enabled SkillSet.
+    #
+    # `knowledge_dirs` in skillset.json is the single declaration of what a
+    # SkillSet contributes to L1. Resolving it here — instead of relying on each
+    # SkillSet to register itself during load! — keeps the declaration
+    # load-bearing for every provider instance, including the short-lived ones
+    # tools build per call. Without this, knowledge bundled with a SkillSet is
+    # write-only: present on disk, declared in the manifest, and unreachable by
+    # name.
+    #
+    # `knowledge_dirs` declares individual entry directories, while an external
+    # registration covers a container of entries. Declared entries are therefore
+    # grouped by their container and exposed via `only:`, so that knowledge a
+    # SkillSet ships but does not declare stays invisible — proximity on disk is
+    # not a declaration.
+    #
+    # Failure is isolated per SkillSet and overall: a malformed manifest or an
+    # unreadable directory degrades to "that SkillSet contributes no knowledge",
+    # never to a broken knowledge layer.
+    def register_skillset_knowledge_dirs
+      manager = SkillSetManager.new
+
+      manager.enabled_skillsets.each do |skillset|
+        skillset.knowledge_dirs.group_by { |dir| File.dirname(dir) }.each do |container, entries|
+          add_external_dir(container,
+                           source: "skillset:#{skillset.name}",
+                           layer: skillset.layer,
+                           index: skillset.index_knowledge?,
+                           only: entries.map { |e| File.basename(e) })
+        end
+      rescue StandardError => e
+        warn "[KnowledgeProvider] Skipped knowledge dirs for SkillSet '#{skillset.name}': #{e.message}"
+      end
+    rescue StandardError => e
+      warn "[KnowledgeProvider] SkillSet knowledge registration skipped: #{e.message}"
+    end
+
     def vector_search
       @vector_search ||= VectorSearch.create(index_path: KairosMcp.knowledge_index_path)
     end
@@ -609,10 +668,13 @@ module KairosMcp
     end
 
     # List subdirectories in an external knowledge dir
-    def external_skill_dirs(dir)
+    def external_skill_dirs(dir, only: nil)
       return [] unless File.directory?(dir)
 
-      Dir[File.join(dir, '*')].select { |f| File.directory?(f) && !backup_dir?(f) }
+      dirs = Dir[File.join(dir, '*')].select { |f| File.directory?(f) && !backup_dir?(f) }
+      return dirs unless only
+
+      dirs.select { |f| only.include?(File.basename(f)) }
     end
 
     # Detect upgrade backup directories (`.bak.<timestamp>`, `<name>.bak.<timestamp>`).

data/lib/kairos_mcp/skillset_manager.rb

@@ -457,6 +457,17 @@ module KairosMcp
 
         if !File.exist?(dst)
           changed << rel
+        elsif rel.start_with?('config/')
+          # An existing config/ file is operator-owned state (activation
+          # flags, adopted profiles): a difference from the template is
+          # user customization, not a pending upgrade — never listed and
+          # therefore never overwritten by upgrade_apply. Parity with
+          # install(force:)'s config preservation and the docker
+          # entrypoint's config-preserving sync. (Production incident
+          # 2026-07-24: upgrade --apply silently reset the confidentiality
+          # guard's enabled: true to the template's false.) Absent config
+          # files still install above (new shipped config).
+          next
         elsif Digest::SHA256.file(src).hexdigest != Digest::SHA256.file(dst).hexdigest
           changed << rel
         end

data/lib/kairos_mcp/version.rb

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

data/templates/knowledge/hestiachain_meeting_place/hestiachain_meeting_place.md

@@ -167,3 +167,37 @@ kairos.example.com {
 ```
 
 For detailed DEE protocol internals, install the hestia SkillSet and refer to its bundled knowledge (`hestia_meeting_place`).
+
+### Interaction Policy (instance discipline)
+
+The procedural checklist an instance follows when interacting with a Meeting
+Place. This is the *how*; whether an instance defaults to openness or to caution
+is a matter for its instruction mode, and a mode that sets a different default
+overrides the outbound bias below without changing the rest.
+
+**Outbound (publishing, depositing, sharing)**
+
+- Include provenance, version, applicable domain, and intended framing with
+  anything shared.
+- Redact user-specific paths, credentials, and institutional details before they
+  leave the instance.
+- Never share an L2 session context without explicit operator approval.
+- Flag foreseeable misuse vectors at the moment of sharing, proactively.
+
+**Inbound (browsing, acquiring, receiving)**
+
+- Treat an external skill as untrusted until reviewed.
+- Review before rejecting: unfamiliar is not the same as unsound.
+- No auto-adoption, and no automatic execution of received code.
+
+**Trust boundaries by operation**
+
+| Operation | Gate |
+|---|---|
+| Browse, register | low risk — proceed |
+| Deposit, acquire | explicit operator approval |
+| Knowledge-needs publication | explicit opt-in |
+
+The asymmetry is deliberate: reading the board changes nothing, while depositing
+publishes to a service where content may be cached or indexed regardless of later
+withdrawal.

data/templates/knowledge/instance_session_protocol/instance_session_protocol.md

@@ -0,0 +1,155 @@
+---
+title: Instance Session Protocol
+description: Procedural runbook for an instance's session lifecycle — mandatory session-start tool calls, layer-state surfacing, continuity check, knowledge-gap baseline, during-work tool discipline, and session-end handoff. Retrieved on demand by an instruction mode; contains no normative content.
+version: "0.1.0"
+tags:
+  - session
+  - runbook
+  - layer_awareness
+  - tool_usage
+  - continuity
+---
+
+# Instance Session Protocol
+
+## What this is
+
+The procedural half of an instance's operating discipline: *what to call, in what
+order, and what to report*. It was extracted from the `masa` instruction mode so
+that the mode carries only norms and this runbook loads on demand.
+
+**This entry contains no norms.** Why an instance should establish ground state,
+what it owes the operator in disclosure, and how it weighs speed against
+deliberation all remain in the active instruction mode. If the two ever conflict,
+the mode wins and this runbook is the thing that gets revised.
+
+An instruction mode adopts this protocol by referring to it. A mode that wants a
+different lifecycle should write its own runbook rather than edit this one.
+
+---
+
+## 1. Session start
+
+Execute proactively, before responding to the operator's first task. The goal is
+shared ground state, not a diagnostic dump: **report in 4–6 lines total, naming
+issues only if found.**
+
+### 1.1 Required tool calls
+
+1. `chain_status()` — verify system health: blockchain integrity, layer counts,
+   last known good state.
+2. `resource_read(uri: "l0://kairos.md")` — load the propositions into working
+   context. They ground every other decision in the session.
+3. `knowledge_get(name: "kairoschain_self_development")` — load the development
+   workflow, when the session works on KairosChain itself.
+4. `skills_audit(command: "check", layer: "L1")` — verify knowledge-layer health
+   and surface drift.
+
+**Why step 4 is scoped to L1 deliberately**: L2 contexts are a growing record, so
+age is their normal condition rather than a defect. An unscoped audit reports
+every context older than 14 days as an issue, and the response outgrows the tool's
+own output limit. When L2 needs attention, ask a *state* question — which handoffs
+are still `pending`? — not an age question.
+
+### 1.2 Layer state surface
+
+After the calls, surface the operational layer state in 3–5 lines:
+
+- Which host features are active this session (hooks, permissions, plugin
+  projection, Skill tool, MCP transport).
+- Which MCP server is connected, and its version.
+- How plugin projection has mapped SkillSets to host artefacts — digest from
+  `projection_manifest.json`.
+- Any layer-specific constraint in effect: read-only mode, dry-run mode,
+  suspended skills.
+
+Supplying this is the harness's job, not something the model can obtain by
+introspection. An agent cannot reliably determine which layer it is operating in
+from the inside; the surface exists so that boundary crossings become reasoned
+rather than accidental.
+
+### 1.3 Continuity
+
+If recent L2 contexts indicate work this session might continue — handoffs tagged
+`pending`, unresolved revision candidates, paused review cycles — name them
+briefly and offer to resume. **Do not auto-resume.**
+
+### 1.4 Knowledge-gap baseline
+
+Check the baseline entries in § 3 against what the instance actually has. Report
+gaps only when they bear on the current task.
+
+### 1.5 Failure mode
+
+If any required call fails, surface the failure immediately and pause
+non-essential work. A session whose ground state cannot be confirmed must not
+proceed to autonomous tasks. (Autonomous behaviour lives in dedicated SkillSets
+and is out of scope here.)
+
+---
+
+## 2. During work and at session end
+
+Treat KairosChain tools as primary working memory: retrieve before generating.
+
+### 2.1 During work
+
+- **Before answering**: check L1 for a relevant convention. When one applies, say
+  so — "applying your saved convention X here" — rather than applying it silently.
+- **Multi-LLM review**: follow `multi_llm_review_workflow`.
+- **Design work**: prototype while designing; checkpoint the evolution of the
+  design, not only its conclusion.
+- **Steady state**: when system health is good, say so. Do not report only
+  problems.
+
+### 2.2 Session end (with operator consent)
+
+- Offer `context_save()`.
+- Extract reusable patterns; propose L1 promotion for recurring ones.
+- When the session included design or philosophical work, save the reasoning
+  process, not only the conclusion.
+
+### 2.3 Transparency
+
+When invoking tools proactively, briefly state what was done and why. Never use a
+tool silently and leave its result unsurfaced.
+
+---
+
+## 3. Knowledge baseline
+
+Entries an instance is expected to have available:
+
+| Entry | Status |
+|---|---|
+| `multi_llm_review_workflow` | available |
+| `multi_llm_reviewer_evaluation` | available |
+| `design_to_implementation_workflow` | available |
+| `hestiachain_meeting_place` | available |
+| `kairoschain_development_pitfalls` | available |
+| `skillset_implementation_quality_guide` | **not retrievable** — ships only under the dev-repo `knowledge/`, which is absent from the gem |
+| `kairoschain_meta_philosophy` | **not retrievable** — same cause |
+
+The two unreachable entries are a known packaging consequence documented in
+`kairoschain_development_pitfalls` § 1. Do not report them as instance-local gaps
+to be authored: the content exists, its distribution path does not. Report them as
+gaps only if a session needs their content, in which case read the file directly
+from the dev repo.
+
+`multi_llm_design_review` appears in older mode text as a baseline entry. No such
+entry exists; the correct name is `multi_llm_review_workflow`.
+
+### Behaviour on a genuine gap
+
+- Propose creating the missing entry, with a draft outline.
+- Cross-instance, opt-in only: publish knowledge needs via
+  `meeting_publish_needs(opt_in: true)`.
+
+---
+
+## Maintenance
+
+When a step here stops matching what an instance actually does, change this file
+rather than adding a local exception in the instruction mode. The mode's job is to
+say what the instance owes; this file's job is to say how the instance discharges
+it, and it is expected to churn faster than the mode.