kairos-chain 2.6.0 → 2.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd37add4e10e999bc03fda6eb9563f61744d2b57e2655cdc855e1b32c42f3cb8
-  data.tar.gz: 581be43b3792007464fced342d535c4af805335dd6a07e748e936fbd8215b130
+  metadata.gz: 00c55f8f91953d2e57924bdc4748c756c3dce18b64a77e8ff17ebed825f506ce
+  data.tar.gz: d4f1a418e9fbeecde4a5a8f9eecc37116b9620b625af0a2e91f09445fd60c673
 SHA512:
-  metadata.gz: 1fb00f60fc782a70af64505c7fa227e2bc01e50286d5697e1302ad67bc4b340c6a4aeecf89339ee03308737fe95fb1000cb10a4a272da5a607bf534947c4d8a1
-  data.tar.gz: f81c3cc36cf14d7d6b959b9c38db00a3ae3a695dc88f5f68dab60468af12b15afad8dad43cb948400c79a2e745085818417a233499023e6b27c65f25adfbe236
+  metadata.gz: 96fc0ef27dcab7f578021254b8e0356644d958fb2da8a61eff02ba9862f02e4542bde04750173edeef0029a34d3a042d308217c17aa98182ebeed134f49a7337
+  data.tar.gz: 0dcbbf48a3c2d1fc6226101b204b1aa7a9f5b0f24e5f1172f29caffd3237195b611aad3684f79034c6528596e5aafa90d0e6750b347b9d5d2e7c419596418747

data/CHANGELOG.md

@@ -4,6 +4,62 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [2.8.0] - 2026-03-08
+
+### Added
+
+- **Knowledge Creator SkillSet** (`knowledge_creator` v1.0.0): New opt-in SkillSet for evaluating and improving L1 knowledge quality through structured Persona Assembly prompts.
+  - `kc_evaluate`: Generate quality evaluation prompts (evaluate/analyze/criteria commands) with 7 evidence-based dimensions, 3-tier readiness assessment (READY/REVISE/DRAFT), and configurable personas (evaluator, guardian, pragmatic)
+  - `kc_compare`: Generate blind A/B comparison prompts for knowledge version comparison (L1 vs L1, L2 vs L1 promotion readiness)
+  - Bundled L1 knowledge: `quality_criteria` (evaluation dimensions, evidence requirements, persona definitions), `creation_guide` (Kairotic Creation Loop workflow, 6 structural patterns)
+  - SkillSet-local persona definitions (does not modify shared `persona_definitions`)
+  - L2 save instruction for evaluation history tracking
+
+- **SkillSet Creator SkillSet** (`skillset_creator` v1.0.0): New opt-in meta-SkillSet for developing KairosChain SkillSets with the 5-phase development workflow.
+  - `sc_design`: Core-vs-SkillSet decision analysis (loads `core_or_skillset_guide` knowledge) and design phase checklist
+  - `sc_scaffold`: Generate complete SkillSet directory structures with skeleton files (preview/generate), input validation (path traversal prevention, collision check), explicit `output_path` required
+  - `sc_review`: Generate structured review prompts for multi-LLM review or Persona Assembly review of SkillSet designs and implementations
+  - Bundled L1 knowledge: `development_guide` (5-phase workflow, review escalation, multi-LLM best practices), `core_or_skillset_guide` (Core vs SkillSet decision tree)
+  - Runtime-detected integration with Knowledge Creator (no declared dependency; uses `defined?` check)
+
+- **Design Process**: Both SkillSets designed through the 5-phase development meta-pattern with 2 rounds of multi-LLM review (Antigravity/Gemini, Claude Team/Opus 4.6, Codex/GPT-5.4). Design documents in `log/`.
+
+---
+
+## [2.7.0] - 2026-03-06
+
+### Added
+
+- **Synoptis Mutual Attestation SkillSet**: New opt-in SkillSet for cross-agent trust verification through cryptographically signed proof envelopes
+  - `ProofEnvelope`: Signed attestation data structure with Merkle root and content hash
+  - `Verifier`: Structural + cryptographic verification with mandatory signature checks
+  - `AttestationEngine`: Attestation lifecycle (create, verify, list) with re-issuance prevention
+  - `RevocationManager`: Authorization-checked revocation (original attester or admin only)
+  - `ChallengeManager`: Challenge/response lifecycle (validity, evidence_request, re_verification)
+  - `TrustScorer`: Weighted composite trust score (quality, freshness, diversity, velocity, revocation penalty)
+  - `Registry::FileRegistry`: Append-only JSONL storage with hash-chain integrity (`_prev_entry_hash`) implementing constitutive recording (Proposition 5)
+  - `Transport`: Abstraction layer for MMP, Hestia, and Local transport mechanisms
+  - 7 MCP tools: `attestation_issue`, `attestation_verify`, `attestation_revoke`, `attestation_list`, `trust_query`, `challenge_create`, `challenge_respond`
+  - 88 unit tests
+
+- **MMP Handler Extension Mechanism**: `MMP::Protocol.register_handler` allows SkillSets to register custom MMP actions without modifying core protocol code. Thread-safe with Mutex, built-in action override prevention.
+
+- **MMP Bearer Token Authentication**: `MMP::PeerManager` now includes `session_token` in Peer struct, extracted during `introduce_to` handshake and sent as `Authorization: Bearer` header on all subsequent messages.
+
+- **MeetingRouter Authenticated Peer Injection**: `MeetingRouter#handle_message` injects `_authenticated_peer_id` into message body, enabling receiving handlers to verify sender identity.
+
+- **SkillSet Eager Loading in HTTP Mode**: `HttpServer` now calls `eager_load_skillsets` during initialization, ensuring SkillSet MMP handlers are registered before the first HTTP request.
+
+- **L1 Knowledge**: Synoptis attestation knowledge (EN/JP) with `readme_order: 4.7` for auto-generated README inclusion.
+
+- **Self-Development Workflow v1.2**: Added SkillSet Release Checklist to `kairoschain_self_development` knowledge (EN/JP) — covers L1 knowledge creation for README, `rake build_readme`, version/changelog updates, and gem build/publish.
+
+### Changed
+
+- **MMP SkillSet**: `meeting.yml` default changed from `enabled: false` to `enabled: true`
+
+---
+
 ## [2.6.0] - 2026-03-05
 
 ### Added
@@ -315,6 +371,8 @@ This project follows [Semantic Versioning](https://semver.org/).
 - Skill promotion with Persona Assembly
 - Tool guide and metadata system
 
+[2.8.0]: https://github.com/masaomi/KairosChain_2026/compare/v2.7.0...v2.8.0
+[2.7.0]: https://github.com/masaomi/KairosChain_2026/compare/v2.6.0...v2.7.0
 [2.6.0]: https://github.com/masaomi/KairosChain_2026/compare/v2.5.0...v2.6.0
 [2.5.0]: https://github.com/masaomi/KairosChain_2026/compare/v2.4.0...v2.5.0
 [2.4.0]: https://github.com/masaomi/KairosChain_2026/compare/v2.3.1...v2.4.0

data/lib/kairos_mcp/http_server.rb

@@ -54,6 +54,17 @@ module KairosMcp
       @admin_router = Admin::Router.new(token_store: @token_store, authenticator: @authenticator)
       @meeting_router = MeetingRouter.new
       @place_router = nil  # Initialized lazily via meeting_place_start tool
+
+      eager_load_skillsets
+    end
+
+    # Load SkillSets at startup so /meeting/* endpoints work immediately.
+    # Without this, MMP module is not defined until the first MCP request.
+    def eager_load_skillsets
+      require_relative 'skillset_manager'
+      SkillSetManager.new.enabled_skillsets.each(&:load!)
+    rescue StandardError => e
+      $stderr.puts "[HttpServer] SkillSet eager load: #{e.message}"
     end
 
     # Start the HTTP server with Puma

data/lib/kairos_mcp/meeting_router.rb

@@ -206,8 +206,10 @@ module KairosMcp
     end
 
     # POST /meeting/v1/message - Generic MMP message handler
+    # Injects authenticated peer_id to prevent from: spoofing in extended handlers.
     def handle_message(env)
       body = parse_body(env)
+      body['_authenticated_peer_id'] = env['meeting.authenticated_peer_id']
       result = protocol.process_message(body)
       json_response(200, result)
     end
@@ -453,6 +455,7 @@ module KairosMcp
         })
       end
 
+      env['meeting.authenticated_peer_id'] = peer_id
       nil # Authentication passed
     end
 

data/lib/kairos_mcp/version.rb

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

data/templates/knowledge/synoptis_attestation/synoptis_attestation.md

@@ -0,0 +1,157 @@
+---
+name: synoptis_attestation
+description: "Synoptis Mutual Attestation — cross-agent trust verification through cryptographic proof envelopes"
+version: 1.0
+layer: L1
+tags: [documentation, readme, synoptis, attestation, trust, p2p, audit, challenge]
+readme_order: 4.7
+readme_lang: en
+---
+
+## Synoptis: Mutual Attestation Protocol (v2.7.0)
+
+### What is Synoptis?
+
+Synoptis is an opt-in SkillSet for cross-agent trust verification through cryptographically signed attestation proofs. It enables agents to attest to facts about any subject (knowledge entries, skill hashes, chain blocks, pipeline outputs, etc.), and provides mechanisms to verify, revoke, and challenge those attestations.
+
+Synoptis is implemented entirely as a SkillSet, preserving KairosChain's principle that new capabilities are expressed as SkillSets rather than core modifications.
+
+### Architecture
+
+```
+KairosChain (MCP Server)
+├── [core] L0/L1/L2 + private blockchain
+├── [SkillSet: mmp] P2P direct mode, /meeting/v1/*
+├── [SkillSet: hestia] Meeting Place + trust anchor
+└── [SkillSet: synoptis] Mutual attestation protocol
+      ├── ProofEnvelope       ← Signed attestation data structure
+      ├── Verifier            ← Structural + cryptographic verification
+      ├── AttestationEngine   ← Attestation lifecycle (create, verify, list)
+      ├── RevocationManager   ← Revocation with authorization checks
+      ├── ChallengeManager    ← Challenge/response lifecycle
+      ├── TrustScorer         ← Weighted trust score calculation
+      ├── Registry::FileRegistry ← Append-only JSONL with hash-chain integrity
+      ├── Transport            ← MMP / Hestia / Local transport abstraction
+      └── tools/               ← 7 MCP tools
+```
+
+### Quick Start
+
+#### 1. Install the synoptis SkillSet
+
+```bash
+# Synoptis depends on MMP. Install both:
+kairos-chain skillset install templates/skillsets/mmp
+kairos-chain skillset install templates/skillsets/synoptis
+```
+
+#### 2. Issue an attestation
+
+In Claude Code / Cursor:
+
+```
+"Attest that knowledge/my_skill has been integrity_verified"
+```
+
+This calls `attestation_issue(subject_ref: "knowledge/my_skill", claim: "integrity_verified")`.
+
+#### 3. Verify and query trust
+
+```
+"What is the trust score for knowledge/my_skill?"
+```
+
+This calls `trust_query(subject_ref: "knowledge/my_skill")`.
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `attestation_issue` | Issue a signed attestation proof for a subject |
+| `attestation_verify` | Verify proof validity (structure, signature, expiry, revocation) |
+| `attestation_revoke` | Revoke an attestation (original attester or admin only) |
+| `attestation_list` | List attestations with optional filters (subject_ref, attester_id) |
+| `trust_query` | Calculate trust score based on attestation history |
+| `challenge_create` | Challenge an existing attestation (validity, evidence_request, re_verification) |
+| `challenge_respond` | Respond to a challenge with additional evidence |
+
+### MMP Integration
+
+Synoptis registers 5 MMP actions via `MMP::Protocol.register_handler`, enabling P2P attestation exchange:
+
+| MMP Action | Description |
+|------------|-------------|
+| `attestation_request` | Request an attestation from a peer |
+| `attestation_response` | Respond with a signed ProofEnvelope |
+| `attestation_revoke` | Broadcast a revocation |
+| `challenge_create` | Send a challenge to the original attester |
+| `challenge_respond` | Respond to a challenge over MMP |
+
+All P2P messages use Bearer token authentication via `MMP::PeerManager`. The authenticated peer ID is injected by `MeetingRouter` as `_authenticated_peer_id`.
+
+### Trust Scoring
+
+Trust scores are calculated as a weighted composite:
+
+| Factor | Weight | Description |
+|--------|--------|-------------|
+| Quality | 0.30 | Ratio of valid (non-revoked, non-expired) attestations |
+| Freshness | 0.25 | Recency of latest attestation (exponential decay, 24h half-life) |
+| Diversity | 0.25 | Number of unique attesters (capped at 5) |
+| Velocity | 0.10 | Attestation rate in the last 7 days |
+| Revocation penalty | −0.10 | Penalty for revoked attestations |
+
+### Registry and Constitutive Recording
+
+All attestation data is stored in append-only JSONL files with hash-chain linking (`_prev_entry_hash`). This implements constitutive recording (Proposition 5): each record irreversibly extends the system's history.
+
+Registry types:
+- `proofs.jsonl` — Attestation proof envelopes
+- `revocations.jsonl` — Revocation records
+- `challenges.jsonl` — Challenge and response records
+
+Use `trust_query` to verify registry integrity — it includes a `registry_integrity.valid` field in its response.
+
+### ProofEnvelope Structure
+
+```json
+{
+  "proof_id": "uuid",
+  "attester_id": "agent_instance_id",
+  "subject_ref": "knowledge/my_skill",
+  "claim": "integrity_verified",
+  "evidence": "manual review of hash chain",
+  "merkle_root": "sha256_of_content",
+  "content_hash": "sha256_of_canonical_json",
+  "signature": "rsa_sha256_signature",
+  "timestamp": "2026-03-06T12:00:00Z",
+  "ttl": 86400,
+  "version": "1.0.0"
+}
+```
+
+### Challenge Workflow
+
+1. Any agent can call `challenge_create(proof_id, challenge_type, details)` to challenge an attestation
+2. The original attester receives the challenge (via MMP or local notification)
+3. The attester calls `challenge_respond(challenge_id, response, evidence)` with additional evidence
+4. Challenge types: `validity` (proof may be incorrect), `evidence_request` (more evidence needed), `re_verification` (conditions may have changed)
+
+### Transport Layer
+
+Synoptis supports multiple transport mechanisms:
+
+| Transport | Backend | Use Case |
+|-----------|---------|----------|
+| MMP | `MMP::PeerManager` | P2P direct attestation exchange |
+| Hestia | `Hestia::PlaceRouter` | Via Meeting Place (future) |
+| Local | Direct registry access | Single-instance and Multiuser mode |
+
+Transport selection is automatic based on available SkillSets.
+
+### Dependencies
+
+- **Required**: MMP SkillSet (>= 1.0.0)
+- **Optional**: Hestia SkillSet (for Meeting Place transport)
+
+For the full protocol specification, install the synoptis SkillSet and refer to its bundled knowledge (`synoptis_protocol`).

data/templates/knowledge/synoptis_attestation_jp/synoptis_attestation_jp.md

@@ -0,0 +1,157 @@
+---
+name: synoptis_attestation_jp
+description: "Synoptis 相互証明 — 暗号署名付き証明エンベロープによるクロスエージェント信頼検証"
+version: 1.0
+layer: L1
+tags: [documentation, readme, synoptis, attestation, trust, p2p, audit, challenge]
+readme_order: 4.7
+readme_lang: jp
+---
+
+## Synoptis：相互証明プロトコル (v2.7.0)
+
+### Synoptis とは
+
+Synoptis は、暗号署名付き証明プルーフによるクロスエージェント信頼検証のためのオプトイン SkillSet です。エージェントはあらゆるサブジェクト（知識エントリ、スキルハッシュ、チェーンブロック、パイプライン出力など）に対して事実を証明でき、その証明を検証・取り消し・チャレンジする仕組みを提供します。
+
+Synoptis は完全に SkillSet として実装されており、新機能をコアではなく SkillSet として表現するという KairosChain の設計原則を保持しています。
+
+### アーキテクチャ
+
+```
+KairosChain (MCP Server)
+├── [core] L0/L1/L2 + private blockchain
+├── [SkillSet: mmp] P2P direct mode, /meeting/v1/*
+├── [SkillSet: hestia] Meeting Place + 信頼アンカー
+└── [SkillSet: synoptis] 相互証明プロトコル
+      ├── ProofEnvelope       ← 署名付き証明データ構造
+      ├── Verifier            ← 構造的 + 暗号学的検証
+      ├── AttestationEngine   ← 証明ライフサイクル（作成・検証・一覧）
+      ├── RevocationManager   ← 認可チェック付き取り消し
+      ├── ChallengeManager    ← チャレンジ/応答ライフサイクル
+      ├── TrustScorer         ← 加重信頼スコア計算
+      ├── Registry::FileRegistry ← ハッシュチェーン付き追記専用 JSONL
+      ├── Transport            ← MMP / Hestia / Local トランスポート抽象
+      └── tools/               ← 7 MCP ツール
+```
+
+### クイックスタート
+
+#### 1. synoptis SkillSet のインストール
+
+```bash
+# Synoptis は MMP に依存します。両方をインストール:
+kairos-chain skillset install templates/skillsets/mmp
+kairos-chain skillset install templates/skillsets/synoptis
+```
+
+#### 2. 証明の発行
+
+Claude Code / Cursor で：
+
+```
+「knowledge/my_skill の整合性を検証済みとして証明して」
+```
+
+これは `attestation_issue(subject_ref: "knowledge/my_skill", claim: "integrity_verified")` を呼び出します。
+
+#### 3. 検証と信頼クエリ
+
+```
+「knowledge/my_skill の信頼スコアは？」
+```
+
+これは `trust_query(subject_ref: "knowledge/my_skill")` を呼び出します。
+
+### MCP ツール
+
+| ツール | 説明 |
+|--------|------|
+| `attestation_issue` | サブジェクトに対する署名付き証明プルーフを発行 |
+| `attestation_verify` | プルーフの有効性を検証（構造、署名、有効期限、取り消し） |
+| `attestation_revoke` | 証明を取り消し（元の証明者または管理者のみ） |
+| `attestation_list` | 証明一覧を表示（subject_ref、attester_id でフィルタ可能） |
+| `trust_query` | 証明履歴に基づく信頼スコアを計算 |
+| `challenge_create` | 既存の証明にチャレンジ（validity、evidence_request、re_verification） |
+| `challenge_respond` | チャレンジに追加証拠で応答 |
+
+### MMP 統合
+
+Synoptis は `MMP::Protocol.register_handler` 経由で5つの MMP アクションを登録し、P2P 証明交換を可能にします：
+
+| MMP アクション | 説明 |
+|---------------|------|
+| `attestation_request` | ピアに証明をリクエスト |
+| `attestation_response` | 署名付き ProofEnvelope で応答 |
+| `attestation_revoke` | 取り消しをブロードキャスト |
+| `challenge_create` | 元の証明者にチャレンジを送信 |
+| `challenge_respond` | MMP 経由でチャレンジに応答 |
+
+すべての P2P メッセージは `MMP::PeerManager` 経由の Bearer トークン認証を使用します。認証済みピア ID は `MeetingRouter` が `_authenticated_peer_id` として注入します。
+
+### 信頼スコアリング
+
+信頼スコアは加重複合値として計算されます：
+
+| 要素 | 重み | 説明 |
+|------|------|------|
+| 品質 (Quality) | 0.30 | 有効な（未取消・未期限切れ）証明の比率 |
+| 鮮度 (Freshness) | 0.25 | 最新証明の新しさ（指数減衰、24時間半減期） |
+| 多様性 (Diversity) | 0.25 | ユニーク証明者の数（上限5） |
+| 速度 (Velocity) | 0.10 | 過去7日間の証明レート |
+| 取消ペナルティ | −0.10 | 取り消された証明に対するペナルティ |
+
+### レジストリと構成的記録
+
+すべての証明データはハッシュチェーン連結（`_prev_entry_hash`）付きの追記専用 JSONL ファイルに保存されます。これは構成的記録（命題5）を実装しています：各レコードはシステムの履歴を不可逆的に拡張します。
+
+レジストリ種別：
+- `proofs.jsonl` — 証明プルーフエンベロープ
+- `revocations.jsonl` — 取り消しレコード
+- `challenges.jsonl` — チャレンジと応答レコード
+
+`trust_query` でレジストリの整合性を検証できます — 応答に `registry_integrity.valid` フィールドが含まれます。
+
+### ProofEnvelope 構造
+
+```json
+{
+  "proof_id": "uuid",
+  "attester_id": "agent_instance_id",
+  "subject_ref": "knowledge/my_skill",
+  "claim": "integrity_verified",
+  "evidence": "ハッシュチェーンの手動レビュー",
+  "merkle_root": "sha256_of_content",
+  "content_hash": "sha256_of_canonical_json",
+  "signature": "rsa_sha256_signature",
+  "timestamp": "2026-03-06T12:00:00Z",
+  "ttl": 86400,
+  "version": "1.0.0"
+}
+```
+
+### チャレンジワークフロー
+
+1. 任意のエージェントが `challenge_create(proof_id, challenge_type, details)` で証明にチャレンジ
+2. 元の証明者がチャレンジを受信（MMP またはローカル通知）
+3. 証明者が `challenge_respond(challenge_id, response, evidence)` で追加証拠とともに応答
+4. チャレンジ種別：`validity`（プルーフが正しくない可能性）、`evidence_request`（追加証拠が必要）、`re_verification`（条件が変化した可能性）
+
+### トランスポート層
+
+Synoptis は複数のトランスポート機構をサポートします：
+
+| トランスポート | バックエンド | 用途 |
+|--------------|------------|------|
+| MMP | `MMP::PeerManager` | P2P 直接証明交換 |
+| Hestia | `Hestia::PlaceRouter` | Meeting Place 経由（将来） |
+| Local | レジストリ直接アクセス | シングルインスタンスおよび Multiuser モード |
+
+トランスポート選択は利用可能な SkillSet に基づいて自動的に行われます。
+
+### 依存関係
+
+- **必須**: MMP SkillSet (>= 1.0.0)
+- **オプション**: Hestia SkillSet（Meeting Place トランスポート用）
+
+プロトコルの完全な仕様については、synoptis SkillSet をインストールし、同梱の knowledge（`synoptis_protocol`）を参照してください。

data/templates/skillsets/knowledge_creator/config/knowledge_creator.yml

@@ -0,0 +1,11 @@
+knowledge_creator:
+  default_evaluate_personas:
+    - evaluator
+    - guardian
+    - pragmatic
+  default_compare_personas:
+    - kairos
+    - pragmatic
+    - skeptic
+  default_assembly_mode: oneshot
+  evaluation_context_prefix: "kc_eval_"

data/templates/skillsets/knowledge_creator/knowledge/creation_guide/creation_guide.md

@@ -0,0 +1,101 @@
+---
+name: creation_guide
+description: >
+  Guide for creating and structuring L1 knowledge in KairosChain.
+  Includes the Kairotic Creation Loop workflow and 6 structural patterns
+  extracted from practical skill analysis. Use when creating new L1 knowledge,
+  restructuring existing knowledge, or analyzing structural patterns.
+  NOT for SkillSet architecture decisions (use core_or_skillset_guide).
+version: "1.0"
+layer: L1
+tags: [meta, creation, workflow, patterns, structure, knowledge]
+---
+
+# L1 Knowledge Creation Guide
+
+## Kairotic Creation Loop
+
+Six phases for creating L1 knowledge. The LLM navigates these naturally in conversation; this is a reference, not a rigid procedure.
+
+| Phase | Action | Key Question |
+|-------|--------|-------------|
+| **RECOGNIZE** | Identify repeating pattern across sessions | Has this come up 3+ times? |
+| **DISTILL** | Extract the reusable core from session context | What's universal vs. session-specific? |
+| **STRUCTURE** | Choose appropriate structural pattern (see below) | What format best serves this content? |
+| **COMPOSE** | Write with proper frontmatter and body | Does description include What + When + NOT? |
+| **EVALUATE** | Apply quality_criteria via kc_evaluate | READY / REVISE / DRAFT? |
+| **ITERATE** | Fix issues and re-evaluate | Are all critical dimensions PASS? |
+
+## 6 Structural Patterns
+
+### 1. Quick Reference Table
+**When**: Any knowledge that maps inputs to outputs or actions to approaches.
+Always place at the top of the document.
+
+```markdown
+| Task | Approach | Notes |
+|------|----------|-------|
+| New MCP tool | SkillSet tool_classes | BaseTool inheritance |
+| New layer concept | Core change | Rare; requires L0 review |
+```
+
+### 2. Deterministic Workflow
+**When**: Multi-step ordered procedures where sequence matters.
+
+```markdown
+## Workflow
+1. Check prerequisites → verify X exists
+2. Execute action → run Y with parameters
+3. Validate result → confirm Z matches expected
+```
+
+### 3. Critical Rules / Pitfalls
+**When**: Domain-specific gotchas that cause repeated errors.
+
+```markdown
+## Critical Rules
+- **NEVER** do X because Y (evidence: Z happened when this was violated)
+- **ALWAYS** check A before B (reason: C depends on A being initialized)
+```
+
+### 4. Multi-Tool Selection
+**When**: Multiple valid approaches exist for the same goal.
+
+```markdown
+| Tool | Best For | Limitation |
+|------|----------|------------|
+| Tool A | Simple cases | Doesn't handle edge case X |
+| Tool B | Complex cases | Slower, requires config Y |
+```
+
+### 5. QA-First Verification
+**When**: Output quality matters and errors are costly. Assume problems exist.
+
+```markdown
+## Verification Checklist
+- [ ] Output matches expected format
+- [ ] No placeholder values remain (search for TODO, FIXME)
+- [ ] Edge cases tested: empty input, large input, special characters
+```
+
+### 6. Session Distillation (L2→L1)
+**When**: Promoting session-specific work to reusable knowledge.
+
+```markdown
+## Distillation Steps
+1. Remove all session-specific references (dates, filenames, user names)
+2. Generalize the procedure: replace specific instances with patterns
+3. Add frontmatter with description that answers: What + When + NOT
+4. Evaluate with kc_evaluate
+```
+
+## Pattern Selection Guide
+
+| Content Type | Primary Pattern | Secondary Pattern |
+|-------------|-----------------|-------------------|
+| Decision guide | Quick Reference Table | Critical Rules |
+| Step-by-step procedure | Deterministic Workflow | QA-First |
+| Tool/approach comparison | Multi-Tool Selection | Quick Reference Table |
+| Domain-specific warnings | Critical Rules | Quick Reference Table |
+| Reusable from session | Session Distillation | (varies by content) |
+| Mixed reference | Quick Reference Table | Deterministic Workflow |

data/templates/skillsets/knowledge_creator/knowledge/quality_criteria/quality_criteria.md

@@ -0,0 +1,76 @@
+---
+name: quality_criteria
+description: >
+  Evidence-based quality evaluation criteria for KairosChain L1 knowledge.
+  Defines evaluation dimensions, PASS/FAIL standards, readiness levels
+  (READY/REVISE/DRAFT), and evaluation persona definitions.
+  Used by kc_evaluate tool. NOT for evaluating code or SkillSet architecture.
+version: "1.0"
+layer: L1
+tags: [meta, quality, evaluation, criteria, personas]
+---
+
+# L1 Knowledge Quality Criteria
+
+## Quick Reference
+
+| Dimension | Question | PASS requires |
+|-----------|----------|---------------|
+| Triggering quality | Does `description` enable accurate identification? | What + When + Negative scope in description |
+| Self-containedness | No session-specific context leaks? | No references to "this session", "today", specific dates |
+| Progressive disclosure | Body vs references/ balance? | Core info in body; details in subdirectories |
+| Evidence | Claims factual and verifiable? | Concrete examples, not vague assertions |
+| Discrimination | Provides info base LLM doesn't have? | KairosChain-specific knowledge the model wouldn't know |
+| Redundancy | Overlap with existing L1? | Minimal overlap; unique perspective or content |
+| Safety alignment | No L0 conflicts? | No contradiction with CLAUDE.md principles |
+
+## Readiness Levels
+
+| Level | Criteria | Action |
+|-------|----------|--------|
+| **READY** | All critical dimensions PASS; no session-specific leaks; description enables accurate triggering | Promote to L1 |
+| **REVISE** | Most dimensions PASS but 1-2 specific issues identified; fixable without redesign | Fix identified issues, re-evaluate |
+| **DRAFT** | Multiple FAILs or fundamental issues; needs significant rework | Return to L2 for further development |
+
+## Evidence Requirements
+
+- PASS requires citing **specific evidence** from the knowledge content
+- Surface-level compliance is FAIL (e.g., frontmatter exists but description is vague)
+- Burden of proof is on the assertion: "it looks fine" is not evidence
+- Each evaluation dimension must include a quoted passage or specific observation
+
+## Evaluation Personas
+
+### evaluator
+- **Role**: Knowledge Quality Inspector
+- **Bias**: High bar for evidence; superficial compliance is failure
+- **Focus**: Can I cite specific evidence for each criterion?
+- **When useful**: Primary evaluation of any L1 knowledge
+
+### guardian
+- **Role**: L0/L1 Boundary Guardian
+- **Bias**: Conservative; protect layer integrity
+- **Focus**: Does this knowledge stay within its declared layer? Could it conflict with L0 meta-rules?
+- **When useful**: Knowledge that touches system behavior, governance, or meta-level concerns
+
+### pragmatic
+- **Role**: Practical Value Assessor
+- **Bias**: Real-world utility over theoretical purity
+- **Focus**: Will an LLM actually use this knowledge effectively in a real session?
+- **When useful**: All evaluations; counterbalance to overly strict evaluation
+
+## Frontmatter Design Guidelines
+
+### description field
+- Format: **What** this knowledge contains + **When** to use it + **Negative scope** (what it's NOT for)
+- Good: "Decision guide for Core vs SkillSet classification. Use when starting new KairosChain feature development. NOT for non-KairosChain projects."
+- Bad: "A guide about SkillSets"
+
+### tags field
+- 5-7 tags maximum
+- Structure: domain tags + function tags + meta tags
+- Example: `[meta, guide, architecture, decision, skillset, core]`
+
+### version field
+- Semver string: "1.0", "0.1", etc.
+- Increment on substantive content changes, not formatting fixes