@dzhechkov/keysarium 1.1.2 → 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,7 +1,7 @@
 {
   "name": "@dzhechkov/keysarium",
-  "version": "1.1.2",
-  "description": "AI Case Research Toolkit for Claude Code — full 7-phase pipeline for AI case studies, hackathons, and casariums",
+  "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": {
     "keysarium": "./bin/cli.js"
@@ -39,5 +39,13 @@
   "homepage": "https://github.com/dzhechko/product-keysarium-2026#readme",
   "bugs": {
     "url": "https://github.com/dzhechko/product-keysarium-2026/issues"
+  },
+  "peerDependencies": {
+    "@dzhechkov/keysarium-core": "^1.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@dzhechkov/keysarium-core": {
+      "optional": true
+    }
   }
 }

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/commands/dream.md

@@ -0,0 +1,101 @@
+# /dream -- Dream Cycles Management
+
+Manage Dream Cycles: trigger dream analysis, view insights, check trigger status.
+
+Dream Cycles build on the reward-calibrated learning system (`lib/memory-protocol.md`,
+`lib/reward-tracker.md`) and background workers (`lib/background-workers.md`).
+
+## Usage
+
+```
+/dream run          — Manually trigger a dream cycle
+/dream insights     — Show latest insights
+/dream status       — Show trigger state
+/dream clear        — Clear old insights (keep last 10)
+```
+
+The argument `$ARGUMENTS` determines which subcommand to execute.
+
+## Protocol
+
+### 1. Parse Subcommand
+
+Parse `$ARGUMENTS` to determine subcommand:
+- If starts with "run" -> execute RUN
+- If starts with "insights" -> execute INSIGHTS
+- If starts with "status" -> execute STATUS
+- If starts with "clear" -> execute CLEAR
+- If empty or unrecognized -> show usage help
+
+### 2. Execute Subcommand
+
+#### RUN: Manually Trigger Dream Cycle
+
+1. Read the DreamEngine protocol: `lib/dream-engine.md`
+2. Read the worker template: `lib/worker-templates/dream-cycle.md`
+3. Read the background workers protocol: `lib/background-workers.md`
+4. Generate a worker ID: `wkr-{YYYYMMDD}-{HHmmss}-dream-cycle`
+5. Create worker directory: `.keysarium/workers/{worker_id}/output/`
+6. Register in `.keysarium/workers/registry.json`
+7. Launch background worker agent with:
+   - Prompt: Contents of `lib/worker-templates/dream-cycle.md` with WORKER_ID, OUTPUT_DIR, TRIGGER_REASON="manual" injected
+   - Model: sonnet
+   - run_in_background: true
+8. Report to user:
+
+```
+Dream cycle started.
+  ID:     {worker_id}
+  Trigger: manual
+  Model:  sonnet
+  Output: .keysarium/workers/{worker_id}/
+
+Use /dream status to check progress.
+Use /dream insights to view results after completion.
+```
+
+#### INSIGHTS: Show Latest Insights
+
+1. Check if `.keysarium/insights/` exists. If not, display empty state.
+2. List all `dream-*.json` files, sort by name DESC, take the first (most recent).
+3. Read the most recent dream result file.
+4. Display insights using the format from `lib/dream-engine.md` (Insight Display Format).
+5. Only show insights with `confidence >= 0.3`.
+6. If no dream files exist, display:
+
+```
+No dream insights available yet.
+
+To generate insights:
+1. Run several cases with /casarium (data is collected automatically)
+2. Run /dream run to trigger analysis
+3. Use /dream insights to view results
+
+Dream insights are generated from accumulated reward data in .keysarium/memory/
+```
+
+#### STATUS: Show Trigger State
+
+1. Read `.keysarium/insights/trigger-state.json`. If missing, display default state.
+2. Calculate time elapsed since `last_dream_completed_at`.
+3. Display using the format from `lib/dream-engine.md` (Status Display Format).
+4. Evaluate triggers and show which are met.
+5. If any trigger is met, suggest running `/dream run`.
+
+#### CLEAR: Clear Old Insights
+
+1. List all `dream-*.json` files in `.keysarium/insights/`.
+2. Sort by name DESC.
+3. Keep the 10 most recent files.
+4. Delete older files.
+5. Report count of deleted files.
+6. If 10 or fewer files exist, report "Nothing to clear."
+
+```
+Dream insights cleanup:
+  Total files: 15
+  Kept: 10 (most recent)
+  Deleted: 5
+
+Trigger state preserved.
+```

package/templates/.claude/commands/feature-adr.md

@@ -0,0 +1,92 @@
+# /feature-adr — Adaptive Feature Development Pipeline
+
+## Использование
+```
+/feature-adr [описание фичи или путь к issue]
+```
+
+## Аргумент
+$ARGUMENTS
+
+## Действия
+
+1. **Загрузи governance shard:** Прочитай `.claude/shards/feature-adr.shard.md`
+2. **Загрузи скилл:** Прочитай `.claude/skills/feature-adr/SKILL.md`
+
+3. **Step 0 — Complexity Router:**
+   - Прочитай `modules/00-complexity-router.md` и `references/complexity-matrix.md`
+   - Классифицируй фичу в S/M/L/XL
+   - Определи `{ACTIVE_STEPS}` и `{TIME_BUDGET}`
+   - Покажи Checkpoint 0 и **жди подтверждения tier**
+
+4. **Steps 1-8 — Execute Active Steps:**
+   - Для каждого шага из `{ACTIVE_STEPS}`:
+     - Прочитай `modules/{step}.md`
+     - Выполни протокол шага
+     - Создай артефакты в `features/<slug>/`
+     - Покажи Checkpoint N
+
+5. **Финализация:**
+   - Создай `features/<slug>/README.md` с summary
+   - Покажи итоговый отчёт
+
+## Создание директории
+
+При первом запуске создай:
+```
+features/<feature-slug>/
+├── diagrams/        ← для Mermaid диаграмм (M+)
+├── 03_adr/          ← для ADR файлов (M+)
+└── 07_code_changes/ ← для манифеста изменений
+```
+
+Slug: kebab-case из описания фичи (латиница, max 40 символов).
+
+## Параллелизация (Agent Swarm)
+
+Для L/XL тiers:
+- Steps 2+3 запускай параллельно (2 агента, sonnet + opus)
+- Steps 4+5 можно параллельно если Step 3 уже завершён
+- Step 7: N параллельных агентов (по одному на модуль)
+- Step 8: 3 параллельных агента (unit ‖ integration ‖ review)
+
+Для S/M: всё последовательно, параллелизация не нужна.
+
+## Model Routing
+
+| Step | Model |
+|------|-------|
+| 0 Router | haiku |
+| 1 Requirements | sonnet |
+| 2 Research | sonnet |
+| 3 ADR | opus |
+| 4 DDD | opus |
+| 5 Architecture | opus |
+| 6 Impl Plan | sonnet |
+| 7 Code | opus |
+| 8 QE | sonnet |
+
+## Checkpoint формат
+
+```
+═══════════════════════════════════════════════════════
+⏸️ STEP N/8: [Step Name] Complete
+<promise>[PROMISE_TAG]</promise>
+Tier: {COMPLEXITY_TIER} | Active Steps: {ACTIVE_STEPS}
+
+[Summary]
+Artifacts: [list] ✅
+
+• "ок" — next step
+• "углуби [section]" — elaborate
+• "[feedback]" — adjust
+═══════════════════════════════════════════════════════
+```
+
+## Critical Rules
+
+- **НИКОГДА** не пропускай Step 0 (Router) — всегда классифицируй сначала
+- **НИКОГДА** не начинай Step 7 (Code) без Step 6 (Plan)
+- **НИКОГДА** не пропускай Step 8 (QE) — тестирование обязательно
+- **ВСЕГДА** жди подтверждения пользователя на Checkpoint перед переходом
+- **ВСЕ артефакты** создаются в `features/<slug>/`, не в корне проекта