@dzhechkov/keysarium 1.2.0 → 1.4.0

package/README.md

@@ -28,10 +28,10 @@ After installation, open Claude Code in your project directory and start using s
 
 | Component | Count | Description |
 |-----------|-------|-------------|
-| **Skills** | 6 | `explore`, `frontend-design`, `goap-research`, `presentation-storyteller`, `problem-solver`, `reverse-engineering` |
-| **Commands** | 13 | `/casarium`, `/new-research`, `/parallel-research`, `/discovery`, `/explore-case`, `/research`, `/cjm-prototype`, `/solve`, `/architecture-phase`, `/presentation`, `/harvest`, `/brain-export`, `/brain-import` |
-| **Rules** | 10 | `research-quality`, `checkpoint-protocol`, `agent-swarm`, `domain-specific`, `anti-patterns`, `file-conventions`, `modular-reuse`, `feedback-loops`, `model-routing`, `trust-tiers` |
-| **Shards** | 8 | Context shards for each phase: `phase-0-discovery`, `phase-1-explore`, `phase-2-research`, `phase-25-cjm`, `phase-3-solve`, `phase-4-architecture`, `phase-5-presentation`, `bto-evaluation` |
+| **Skills** | 8 | `explore`, `frontend-design`, `goap-research`, `presentation-storyteller`, `problem-solver`, `reverse-engineering`, `bto`, `knowledge-extractor` |
+| **Commands** | 24 | `/casarium`, `/new-research`, `/parallel-research`, `/discovery`, `/explore-case`, `/research`, `/cjm-prototype`, `/solve`, `/architecture-phase`, `/presentation`, `/harvest`, `/brain-export`, `/brain-import`, `/bto`, `/bto-build`, `/bto-test`, `/bto-optimize`, `/bto-benchmark`, `/feature-adr`, `/init-platform`, `/learning-stats`, `/dream`, `/workers`, `/verify-chain` |
+| **Rules** | 16 | `research-quality`, `checkpoint-protocol`, `agent-swarm`, `domain-specific`, `anti-patterns`, `file-conventions`, `modular-reuse`, `feedback-loops`, `model-routing`, `trust-tiers`, `bto-quality-gates`, `background-workers`, `dream-cycles`, `reward-learning`, `witness-chain`, `feature-adr-conventions` |
+| **Shards** | 9 | Context shards for each phase: `phase-0-discovery`, `phase-1-explore`, `phase-2-research`, `phase-25-cjm`, `phase-3-solve`, `phase-4-architecture`, `phase-5-presentation`, `bto-evaluation`, `feature-adr` |
 | **Agent Templates** | 5 | `discovery-worker`, `research-worker`, `cjm-variant-worker`, `presentation-worker`, `parallel-research-orchestrator` |
 | **Library** | 4 | `phase-utils`, `agent-patterns`, `skill-loader`, `domain-templates` |
 | **Documentation** | 12 | Deployment, admin, user guide, infrastructure, architecture, flows (for Keysarium and BTO) |
@@ -255,29 +255,47 @@ Create a new file under `.claude/rules/`:
 
 Rules are automatically loaded by Claude Code and enforced across all phases.
 
-### Knowledge Harvesting
+### Knowledge Harvesting (knowledge-extractor skill)
 
-After completing research, extract reusable patterns:
+After completing research, extract reusable patterns using the multi-agent knowledge-extractor:
 
 ```bash
-/harvest researches/<slug>/     # Harvest from one research
-/harvest all                    # Harvest from all researches
+/harvest researches/<slug>/                    # Full harvest from one directory
+/harvest researches/<slug>/ only patterns      # Extract only patterns
+/harvest all                                   # Harvest from all researches
+/harvest all only rules,templates              # All researches, specific categories
+/harvest features/my-feature/                  # Harvest from a feature directory
 ```
 
-The harvester reviews completed projects, identifies universal patterns, decontextualizes them, and updates `TOOLKIT_HARVEST.md`.
+**Pipeline:** Extract (5 parallel agents) → Classify (7 categories) → User Checkpoint → Gate (8 quality checks) → Integrate (auto-place)
 
-### Brain Portability
+| Stage | What Happens |
+|-------|-------------|
+| **Extract** | 5 parallel agents scan through different lenses: patterns, commands, rules, templates, snippets |
+| **Classify** | Findings sorted into 7 categories (`skills`, `commands`, `hooks`, `rules`, `templates`, `patterns`, `snippets`) with cross-dedup |
+| **User Review** | Numbered list of findings with granular control (`#N` commands to accept/reject/merge) |
+| **Quality Gates** | 8 blocking gates in 2 passes: deterministic (G1-G2, G5-G7) + semantic via haiku (G3-G4, G8) |
+| **Integrate** | Auto-placement into `.claude/` directories + `TOOLKIT_HARVEST.md` update + harvest report |
+
+The skill is **domain-agnostic** — works in any project, not just Keysarium research pipelines. Optional integrations (reward learning, dream cycles, brain export) activate automatically when their infrastructure is present.
+
+### 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.4.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/src/utils.js

@@ -218,7 +218,7 @@ function getTemplatesDir() {
 // ===========================================================================
 
 const COMPONENTS = {
-  skills:    { src: '.claude/skills',         label: 'Skills (6 skill packs)',            group: 'core' },
+  skills:    { src: '.claude/skills',         label: 'Skills (8 skill packs)',            group: 'core' },
   commands:  { src: '.claude/commands',        label: 'Commands (13 slash commands)',      group: 'core' },
   rules:     { src: '.claude/rules',           label: 'Rules (10 auto-loaded rules)',     group: 'core' },
   shards:    { src: '.claude/shards',          label: 'Shards (7 context shards)',        group: '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,16 @@ Construct a JSON structure:
     "bto_evaluations_run": 0
   },
 
+  "reward_data": {
+    "total_records": 0,
+    "domains": [],
+    "phase_averages": {},
+    "top_patterns": [],
+    "most_reused_records": [],
+    "total_usage_count": 0,
+    "exported_from": ".keysarium/memory/"
+  },
+
   "metadata": {
     "export_scope": "all|[specific path]",
     "files_scanned": 0,
@@ -87,23 +121,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 +197,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