@dzhechkov/keysarium 1.2.0 → 1.3.0

package/README.md

@@ -266,18 +266,23 @@ After completing research, extract reusable patterns:
 
 The harvester reviews completed projects, identifies universal patterns, decontextualizes them, and updates `TOOLKIT_HARVEST.md`.
 
-### Brain Portability
+### Brain Portability (v1.1)
 
 Export and import accumulated knowledge between projects:
 
 ```bash
-# Export knowledge as a portable JSON container
+# Export knowledge as a portable JSON container (v1.1 with manifest + checksum)
 /brain-export
 
+# Delta export — store only changes since last export (COW mode)
+/brain-export --delta keysarium-brain-2026-03-01.json
+
 # Import a brain container into another project
 /brain-import path/to/brain.json
 ```
 
+**v1.1 features:** SHA-256 integrity manifest, delta exports via JSON Patch (RFC 6902), 2-tier memory index, HOT/WARM/COLD/PURGE record lifecycle. Backward compatible with v1.0 brain files.
+
 ### Context Shards
 
 Shards (`.claude/shards/`) are lightweight context fragments that phases load on demand. They keep the main CLAUDE.md lean while providing phase-specific instructions, semantic completion promises, and quality checklists.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/keysarium",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "AI Case Research Toolkit for Claude Code — full 7-phase pipeline with feature-adr, dream cycles, background workers, multi-platform support, and reward learning",
   "main": "src/cli.js",
   "bin": {
@@ -41,7 +41,7 @@
     "url": "https://github.com/dzhechko/product-keysarium-2026/issues"
   },
   "peerDependencies": {
-    "@dzhechkov/keysarium-core": "^1.0.0"
+    "@dzhechkov/keysarium-core": "^1.1.0"
   },
   "peerDependenciesMeta": {
     "@dzhechkov/keysarium-core": {

package/templates/.claude/commands/brain-export.md

@@ -1,6 +1,6 @@
 ---
 description: "Export accumulated knowledge as a portable brain container (JSON)"
-argument: "optional path to specific research directory, or 'all' for everything"
+argument: "optional path to specific research directory, 'all' for everything, or '--delta <parent-file>' for COW export"
 ---
 
 # Brain Export — Portable Knowledge Container
@@ -8,37 +8,61 @@ argument: "optional path to specific research directory, or 'all' for everything
 Export accumulated knowledge, patterns, and evaluations into a portable JSON container
 that can be imported into other projects.
 
+Supports **full export** (default) and **delta export** (COW mode, v1.1).
+
 ## Protocol
 
-### Step 1: Scan Knowledge Sources
+### Step 1: Parse Arguments & Detect Mode
+
+1. If `$ARGUMENTS` contains `--delta <path>`:
+   - Set mode = `delta`
+   - Load parent brain file from `<path>`
+   - Verify parent is valid (`format` = `"keysarium-brain"`, has `manifest` or `version`)
+   - If parent has `manifest.checksum`, note it for verification
+   - Remaining arguments = export scope
+2. Otherwise: set mode = `full`
+3. If `$ARGUMENTS` specifies a path (not `--delta`), export only from that directory
+4. If `$ARGUMENTS` is "all" or empty, export from all sources
+
+### Step 2: Scan Knowledge Sources
 
 Scan the following sources for exportable knowledge:
 1. `TOOLKIT_HARVEST.md` — harvested patterns and learnings
 2. `researches/*/` — all completed research directories
 3. `.claude/skills/*/SKILL.md` — skill metadata and trust tiers
 4. BTO evaluation reports (if any exist in researches)
+5. `.keysarium/memory/` — reward data aggregates (if exists)
 
-If `$ARGUMENTS` specifies a path, export only from that directory.
-If `$ARGUMENTS` is "all" or empty, export from all sources.
+### Step 3: Build Brain Container
 
-### Step 2: Build Brain Container
-
-Construct a JSON structure:
+Construct a JSON structure (v1.1 with manifest):
 
 ```json
 {
-  "version": "1.0",
+  "version": "1.1",
   "format": "keysarium-brain",
-  "exported_at": "[ISO 8601 timestamp]",
-  "source_project": "product-keysarium-2026",
-  "source_branch": "[current git branch]",
+  "manifest": {
+    "created_at": "[ISO 8601 timestamp]",
+    "source_project": "[project directory name]",
+    "source_branch": "[current git branch]",
+    "checksum": "sha256:[computed after content assembly]",
+    "record_count": "[total items across all sections]",
+    "domains": ["[list of domains found]"],
+    "skills": ["[list of skill names found]"],
+    "research_count": "[number of research summaries]",
+    "harvest_pattern_count": "[number of harvest patterns]",
+    "size_bytes": "[approximate payload size]",
+    "parent": null,
+    "parent_checksum": null,
+    "delta_type": null
+  },
 
   "skills": {
     "[skill-name]": {
-      "trust_tier": 0-3,
+      "trust_tier": "0-3",
       "trust_tier_label": "Advisory|Structured|Validated|Verified",
-      "bto_score": null or float,
-      "last_evaluated": null or ISO date
+      "bto_score": "null or float",
+      "last_evaluated": "null or ISO date"
     }
   },
 
@@ -57,7 +81,7 @@ Construct a JSON structure:
       "phases_completed": ["list of completed phases"],
       "key_findings": ["top 3-5 findings"],
       "chosen_cjm_variant": "A|B|C|D or null",
-      "presentation_score": null or float
+      "presentation_score": "null or float"
     }
   ],
 
@@ -79,6 +103,14 @@ Construct a JSON structure:
     "bto_evaluations_run": 0
   },
 
+  "reward_data": {
+    "total_records": 0,
+    "domains": [],
+    "phase_averages": {},
+    "top_patterns": [],
+    "exported_from": ".keysarium/memory/"
+  },
+
   "metadata": {
     "export_scope": "all|[specific path]",
     "files_scanned": 0,
@@ -87,23 +119,67 @@ Construct a JSON structure:
 }
 ```
 
-### Step 3: Write Export File
-
-Write the JSON to: `keysarium-brain-[YYYY-MM-DD].json` in the project root.
-
-### Step 4: Generate Summary
+### Step 3a: Compute Manifest
+
+After assembling all content sections:
+
+1. Serialize all sections except `manifest` as JSON (sorted keys, compact)
+2. Compute SHA-256 of the serialized string
+3. Set `manifest.checksum` = `"sha256:{64-hex-chars}"`
+4. Count total records: skills + research_summaries + harvest_patterns
+5. Set `manifest.record_count`, `manifest.domains`, `manifest.skills`, `manifest.research_count`, `manifest.harvest_pattern_count`
+6. Set `manifest.size_bytes` = byte length of serialized content
+
+### Step 3b: Delta Mode (if mode = delta)
+
+If exporting in delta mode:
+
+1. Compare current full container with parent container section by section
+2. Generate JSON Patch (RFC 6902) operations:
+   - `add` for new entries (new skills, new research summaries, new patterns)
+   - `replace` for changed values (updated trust tiers, new BTO scores)
+   - `remove` for deleted entries (rare)
+3. If patch is empty → log "No changes since parent export" and stop
+4. Build delta container:
+   ```json
+   {
+     "version": "1.1",
+     "format": "keysarium-brain",
+     "manifest": {
+       "...same fields...",
+       "parent": "[parent-filename]",
+       "parent_checksum": "sha256:[parent's checksum]",
+       "delta_type": "rfc6902"
+     },
+     "patch": [ ...RFC 6902 operations... ]
+   }
+   ```
+5. `manifest.checksum` = SHA-256 of the `patch` array
+6. `manifest.record_count` = number of patch operations
+
+### Step 4: Write Export File
+
+- **Full mode:** Write to `keysarium-brain-[YYYY-MM-DD].json` in project root
+- **Delta mode:** Write to `keysarium-brain-[YYYY-MM-DD]-delta.json` in project root
+
+### Step 5: Generate Summary
 
 Display:
 ```
 ═══════════════════════════════════════════════════════
 Brain Export Complete
 
+Mode: [full|delta]
 File: keysarium-brain-[date].json
 Size: [file size]
+Checksum: sha256:[first 12 chars]...
+Parent: [parent filename or "none"]
+
 Skills exported: [N] (tiers: [breakdown])
 Research summaries: [N]
 Harvest patterns: [N]
 Domain patterns: [N domains]
+Reward data: [N records aggregated]
 
 Import into another project:
   /brain-import keysarium-brain-[date].json
@@ -119,3 +195,4 @@ This export format is project-agnostic. Any multi-phase pipeline can:
 1. Define its own brain schema extending the base format
 2. Export domain-specific patterns
 3. Import patterns from other pipelines
+4. Use delta mode for efficient incremental exports

package/templates/.claude/commands/brain-import.md

@@ -7,17 +7,71 @@ argument: "path to brain JSON file"
 
 Import a previously exported brain container to bootstrap knowledge in a new project.
 
+Supports v1.0 (legacy) and v1.1 (manifest + delta) containers.
+
 ## Protocol
 
 ### Step 1: Validate Brain File
 
 1. Read the JSON file from `$ARGUMENTS`
 2. Validate format:
-   - `version` field exists and is "1.0"
-   - `format` field is "keysarium-brain"
+   - `format` field is `"keysarium-brain"`
+   - `version` field exists and is `"1.0"` or `"1.1"`
    - Required sections present: `skills`, `harvest_patterns`, `metadata`
 3. If validation fails → show error and stop
 
+### Step 1a: Read Manifest (v1.1)
+
+If `version` is `"1.1"` and `manifest` object exists:
+
+1. Display manifest summary:
+   ```
+   ═══════════════════════════════════════════════════════
+   Brain Manifest
+
+   Source: [manifest.source_project]
+   Branch: [manifest.source_branch]
+   Created: [manifest.created_at]
+   Checksum: sha256:[first 12 chars]...
+   Type: [full | delta (parent: manifest.parent)]
+
+   Contents:
+     Domains: [manifest.domains]
+     Skills: [manifest.skills] ([count])
+     Research summaries: [manifest.research_count]
+     Harvest patterns: [manifest.harvest_pattern_count]
+     Total records: [manifest.record_count]
+     Size: [manifest.size_bytes] bytes
+   ═══════════════════════════════════════════════════════
+   ```
+
+2. Verify integrity: compute SHA-256 of content sections, compare with `manifest.checksum`
+   - If match → display "Integrity: verified"
+   - If mismatch → display "WARNING: Checksum mismatch! File may be corrupted or manually edited."
+   - Checksum mismatch does NOT block import — it is a warning only
+
+### Step 1b: Resolve Delta (v1.1, COW mode)
+
+If `manifest.parent` is not null (this is a delta container):
+
+1. Log: "Delta container detected. Parent: [manifest.parent]"
+2. Search for parent file:
+   - Same directory as the delta file
+   - Project root directory
+   - If not found → ask user: "Parent file [name] not found. Provide path or type 'partial' for partial import"
+3. If parent found:
+   a. Load parent file
+   b. If parent also has `manifest.parent` → resolve recursively (chain)
+   c. If chain depth > 3 → warn: "Deep delta chain (depth [N]). Consider re-exporting a full brain."
+   d. Verify `manifest.parent_checksum` matches parent's actual checksum (warn if mismatch)
+   e. Apply JSON Patch (RFC 6902) operations from `patch` array to parent content
+   f. Result = fully materialized brain container. Proceed with standard import.
+4. If parent NOT found and user chose 'partial':
+   - Extract only self-contained `add` operations from `patch` array
+   - Convert each `add` value to a standalone entry
+   - Proceed with import using only these extracted entries
+   - Log: "Partial import: [N] add operations applied, [M] operations skipped (require parent context)"
+
 ### Step 2: Selective Import
 
 Ask user what to import:
@@ -25,7 +79,7 @@ Ask user what to import:
 ```
 Brain file: [filename]
 Source project: [source_project]
-Exported: [exported_at]
+Exported: [exported_at or manifest.created_at]
 
 Available sections:
   [1] Skills metadata ([N] skills) — trust tiers and BTO scores
@@ -33,6 +87,7 @@ Available sections:
   [3] Research summaries ([N] cases) — findings and CJM choices
   [4] Harvest patterns ([N] patterns) — reusable patterns and snippets
   [5] Pipeline metrics — timing and performance data
+  [6] Reward data — phase averages and top patterns
   [A] All sections
 
 Which sections to import? (comma-separated numbers or 'A' for all)
@@ -65,6 +120,10 @@ For each imported section:
 - Store as reference baseline
 - Don't overwrite current project metrics
 
+**Reward data:**
+- Store phase averages as reference in `.keysarium/memory/_stats/imported-baselines.json`
+- Don't overwrite existing reward records
+
 ### Step 4: Write Import Log
 
 Create `brain-import-log-[YYYY-MM-DD].md` in project root:
@@ -74,6 +133,9 @@ Create `brain-import-log-[YYYY-MM-DD].md` in project root:
 
 - Source: [filename]
 - Source project: [source_project]
+- Version: [version]
+- Type: [full | delta]
+- Checksum verified: [yes | no | n/a (v1.0)]
 - Imported at: [timestamp]
 - Sections imported: [list]
 
@@ -82,6 +144,11 @@ Create `brain-import-log-[YYYY-MM-DD].md` in project root:
 
 ## Conflicts Resolved
 - [any deduplication or merge decisions]
+
+## Delta Resolution (if applicable)
+- Parent: [parent filename]
+- Chain depth: [N]
+- Patch operations applied: [N]
 ```
 
 ### Step 5: Summary
@@ -91,6 +158,8 @@ Create `brain-import-log-[YYYY-MM-DD].md` in project root:
 Brain Import Complete
 
 Source: [filename]
+Version: [version] | Type: [full|delta]
+Integrity: [verified | warning | n/a]
 Sections imported: [list]
 Skills updated: [N]
 Patterns merged: [N]
@@ -106,7 +175,9 @@ Import log: brain-import-log-[date].md
 ## Modular Reuse
 
 The import protocol handles:
-- Version compatibility checking
+- Version compatibility checking (v1.0 and v1.1)
+- Manifest integrity verification (v1.1)
+- Delta resolution with parent chain (v1.1 COW)
 - Selective import (user chooses sections)
 - Merge-not-overwrite strategy
 - Conflict resolution with logging

package/templates/CLAUDE.md

@@ -103,6 +103,7 @@ product-keysarium-2026/
 ├── packages/                       ← npm пакеты
 │   ├── dz-keysarium/              ← @dzhechkov/keysarium (research pipeline)
 │   ├── dz-skills-bto/             ← @dzhechkov/skills-bto (BTO evaluation)
+│   ├── dz-feature-adr/            ← @dzhechkov/skills-feature-adr (feature development)
 │   └── dz-keysarium-core/         ← @dzhechkov/keysarium-core (shared framework)
 │       ├── governance/             ← Constitution + shards + checkpoints
 │       ├── memory/                 ← Learning protocol + reward + dream engine
@@ -188,30 +189,35 @@ DISCOVERY → EXPLORE  → RESEARCH → CJM PROTO    → SOLVE    → ARCHITECTU
 6 именованных loops формализуют передачу данных между фазами.
 См. `.claude/rules/feedback-loops.md` для Variable Registry.
 
-## Portable Brain
+## Portable Brain (v1.1)
 
 ```
-/brain-export [путь или "all"]  — Экспорт знаний в JSON контейнер
-/brain-import [файл.json]       — Импорт знаний из другого проекта
+/brain-export [путь или "all"]               — Экспорт знаний в JSON контейнер (v1.1 с manifest)
+/brain-export --delta <parent-brain.json>     — Дельта-экспорт (COW, JSON Patch RFC 6902)
+/brain-import [файл.json]                     — Импорт знаний из другого проекта
 ```
 
-Brain container включает: skill metadata, domain patterns, research summaries,
-harvest patterns, pipeline metrics. Selective import с merge-not-overwrite стратегией.
+Brain container v1.1 включает: SHA-256 manifest с checksum, skill metadata, domain patterns,
+research summaries, harvest patterns, pipeline metrics, reward data.
+Selective import с merge-not-overwrite стратегией. Backward compatible с v1.0.
+
+**v1.1 features:** Integrity manifest, delta exports (COW branching), 2-tier memory index,
+HOT/WARM/COLD/PURGE record lifecycle.
 
 ## keysarium-core — Shared Framework Package
 
 `@dzhechkov/keysarium-core` — домен-агностичный фреймворк для multi-agent пайплайнов. Содержит протоколы, которые используются и в Keysarium, и в BTO, и могут быть использованы любой командой для создания собственного пайплайна.
 
-### Архитектура 3 пакетов
+### Архитектура 4 пакетов
 
 ```
-@dzhechkov/keysarium-core          ← Общий фреймворк (NEW)
-        ^                ^
-        |                |
-   peerDep          peerDep
-        |                |
-@dzhechkov/keysarium    @dzhechkov/skills-bto
-  (исследования)         (оценка)
+            @dzhechkov/keysarium-core              ← Общий фреймворк
+                ^         ^         ^
+                |         |         |
+           peerDep    peerDep   peerDep
+                |         |         |
+@dzhechkov/keysarium  skills-bto  skills-feature-adr
+  (исследования)       (оценка)    (фичи)
 ```
 
 ### Модули core
@@ -219,7 +225,7 @@ harvest patterns, pipeline metrics. Selective import с merge-not-overwrite ст
 | Модуль | Файлы | Назначение |
 |--------|-------|-----------|
 | governance/ | 3 | Constitution, shard protocol, checkpoint/promise protocol |
-| memory/ | 3 | memory_query/store, reward tracking, dream engine |
+| memory/ (v1.1) | 3 | memory_query/store, reward tracking, dream engine, **2-tier index, COW branching, record lifecycle** |
 | orchestration/ | 4 | Queen protocol, 6 topologies, workers, model routing |
 | verification/ | 3 | Witness chain, judge attestation, audit trail |
 | trust-tiers/ | 2 | 4-tier classification, promotion protocol |