@dzhechkov/keysarium 1.3.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,16 +255,29 @@ 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)
+
+| 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)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/keysarium",
-  "version": "1.3.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": {

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

@@ -108,6 +108,8 @@ Construct a JSON structure (v1.1 with manifest):
     "domains": [],
     "phase_averages": {},
     "top_patterns": [],
+    "most_reused_records": [],
+    "total_usage_count": 0,
     "exported_from": ".keysarium/memory/"
   },
 

package/templates/.claude/commands/bto-benchmark.md

@@ -0,0 +1,302 @@
+# /bto-benchmark — Deterministic Benchmarking of a Skill or Command
+
+## Usage
+```
+/bto-benchmark [path to skill directory or file]
+```
+
+## Parameters
+- $ARGUMENTS — Path to a skill directory (`.claude/skills/<name>/`), a command file (`.claude/commands/<name>.md`), a rule file (`.claude/rules/<name>.md`), or any structured artifact. Optionally include "verbose" to show expanded per-section diagnostics for all layers.
+
+## Protocol
+
+### Step 1: Load Skill and Module
+
+Read `.claude/skills/bto/SKILL.md`
+Read `.claude/skills/bto/modules/benchmark.md`
+Read `.claude/skills/bto/references/golden-samples.md`
+
+### Step 2: Validate Input
+
+If $ARGUMENTS is empty:
+- Ask: "Provide a path to the skill directory or artifact file you want to benchmark."
+- Stop and wait.
+
+Resolve the artifact path from $ARGUMENTS:
+- Strip any trailing slash
+- If the path points to a directory → look for `SKILL.md` inside it as the primary file, but include all files in the directory for context
+- If the path points to a file → use that file directly
+- If the path does not exist → report "Path not found: [path]" and stop
+
+### Step 3: Detect Artifact Type
+
+Auto-detect from path pattern:
+
+| Path Pattern | Detected Type |
+|-------------|--------------|
+| `.claude/skills/*/SKILL.md` or `.claude/skills/*/` | skill |
+| `.claude/commands/*.md` | command |
+| `.claude/rules/*.md` | rule |
+| `.claude/agents/*.md` | agent |
+| `researches/**/*.md` | research artifact |
+
+If type cannot be determined from path → infer from file content structure.
+
+### Step 4: Layer B0 — Golden Sample Comparison (Deterministic)
+
+**Purpose:** Compare artifact structure against the canonical golden sample for its type. Zero LLM cost.
+
+Load golden samples for the detected type from `references/golden-samples.md`.
+
+**Procedure:**
+
+1. Parse the artifact into a section tree (heading hierarchy, section lengths, ordering)
+2. Parse the matching golden sample into the same section tree format
+3. Compare across three structural axes:
+
+**Axis 1 — Section Coverage:**
+For each required section in the golden sample, check if the artifact contains a matching section (by heading text or semantic equivalent).
+- `section_coverage = matched_sections / total_golden_sections`
+
+**Axis 2 — Ordering Score:**
+Compare the ordering of matched sections against the golden sample ordering.
+- Use normalized Kendall tau distance: `ordering_score = 1 - (inversions / max_inversions)`
+- If fewer than 3 matched sections → ordering_score = 1.0 (too few to meaningfully compare)
+
+**Axis 3 — Proportion Score:**
+For each matched section, compute the ratio of artifact section length to golden sample section length.
+- `proportion_score = 1 - mean(|log(artifact_len / golden_len)|)` clamped to [0, 1]
+- Measures whether sections are proportionally sized (not too bloated, not too thin)
+
+**Display per-section MATCH/MISS table:**
+
+```
+Golden Section              Status    Artifact Section             Size Ratio
+─────────────────────────── ──────── ──────────────────────────── ──────────
+## Overview                 MATCH    ## Overview                  1.2x
+## Protocol                 MATCH    ## Protocol                  0.8x
+## Anti-Patterns            MATCH    ## Anti-Patterns             1.0x
+## Dependencies             MISS     —                            —
+## Quick Start              MATCH    ## Quick Start               1.5x
+```
+
+**Golden Similarity Score:**
+```
+B0 = section_coverage * 0.50 + ordering_score * 0.25 + proportion_score * 0.25
+```
+
+**Gate:** If B0 < 0.30 → BLOCK immediately. The artifact's structure is too far from the expected form to benchmark meaningfully.
+
+### Step 5: Layer B1 — Deterministic Test Suite
+
+**Purpose:** Run all applicable deterministic tests for the detected artifact type. Zero LLM cost.
+
+Execute all applicable checks from `benchmark.md` for the detected artifact type. These overlap with but extend the Layer 0 checks from `/bto-test`:
+
+**Universal Checks (U1-U12):**
+- U-01: File exists and is non-empty
+- U-02: UTF-8 encoding valid
+- U-03: Starts with level-1 heading
+- U-04: No placeholder text (`[TODO]`, `[TBD]`, `<INSERT>`, `[PLACEHOLDER]`)
+- U-05: No empty sections (heading with no content before next heading)
+- U-06: Consistent heading hierarchy (no h1→h3 jumps)
+- U-07: No broken internal cross-references
+- U-08: File size within bounds (200B – 100KB per file)
+- U-09: No trailing whitespace on lines
+- U-10: Standard Markdown only (no HTML unless in code blocks)
+- U-11: All code blocks properly closed
+- U-12: No duplicate top-level sections
+
+**Type-Specific Checks:**
+- Skill: SK-01 through SK-16 (SKILL.md exists, required sections, modules/, references/, examples/, etc.)
+- Command: CM-01 through CM-08 (Usage section, Parameters, Protocol steps, Checkpoint, Critical Rules, etc.)
+- Rule: RL-01 through RL-06 (Table format, detection signals, fix actions, no contradictions, etc.)
+- Agent: AG-01 through AG-04 (Model specified, isolation rules, naming convention, output format)
+
+**Display per-test PASS/FAIL table:**
+
+```
+ID      Check                              Result   Note
+─────── ──────────────────────────────────  ──────── ────────────────────────────
+U-01    File exists and is non-empty       PASS     8.4 KB
+U-02    UTF-8 encoding                     PASS
+...
+SK-01   SKILL.md exists at skill root      PASS
+SK-02   Has ## Overview section            PASS
+SK-03   Has ## Anti-Patterns section       FAIL     Section missing
+...
+```
+
+**Test Pass Rate:**
+```
+B1 = passed_tests / total_applicable_tests
+```
+
+**Gate:** If B1 < 0.60 → BLOCK. Too many structural failures to proceed to consistency probing.
+
+### Step 6: Layer B2 — Consistency Probe
+
+**Purpose:** Measure evaluation stability by running identical prompts across multiple agents. Detects artifacts that produce inconsistent interpretations.
+
+**Model:** haiku (cost-optimized)
+
+**Spawn 3 parallel haiku agents with the identical evaluation prompt:**
+
+Each agent receives the exact same prompt:
+```
+You are evaluating a Claude Code artifact for structural quality.
+Rate these 4 dimensions (0.0 to 1.0 each, two decimal places):
+1. STRUCTURE — Does the artifact follow a clear, logical organization?
+2. CLARITY — Are instructions unambiguous and actionable?
+3. COVERAGE — Does it address all aspects implied by its title/scope?
+4. CONSISTENCY — Is the internal terminology and style uniform?
+Output as JSON: {"structure": X.XX, "clarity": X.XX, "coverage": X.XX, "consistency": X.XX}
+```
+
+**Isolation:** Each agent evaluates independently. No cross-communication.
+
+**After all 3 return, compute structural agreement:**
+
+For each dimension:
+```
+agreement[dim] = 1 - (max(scores[dim]) - min(scores[dim]))
+```
+
+**Consistency Score:**
+```
+B2 = mean(agreement across all 4 dimensions)
+```
+
+**Interpretation:**
+- B2 > 0.85 → HIGH consistency — the artifact is unambiguously structured
+- B2 0.60-0.85 → MODERATE consistency — some sections are open to interpretation
+- B2 < 0.60 → LOW consistency — the artifact is structurally ambiguous
+
+**Display per-probe comparison:**
+
+```
+Dimension      Probe 1   Probe 2   Probe 3   Range    Agreement
+──────────── ────────── ────────── ────────── ──────── ──────────
+STRUCTURE      0.80       0.85       0.82      0.05     0.95
+CLARITY        0.70       0.75       0.65      0.10     0.90
+COVERAGE       0.60       0.70       0.55      0.15     0.85
+CONSISTENCY    0.75       0.78       0.73      0.05     0.95
+                                                Mean:    0.91
+```
+
+No gate on B2 — consistency is informational and feeds into the aggregate score.
+
+### Step 7: Layer B3 — Performance Metrics
+
+**Purpose:** Quantify token efficiency and information density. Zero LLM cost.
+
+**Metric 1 — Token Efficiency:**
+```
+token_efficiency = meaningful_content_tokens / total_tokens
+```
+Where `meaningful_content_tokens` excludes: blank lines, decorative separators, repeated boilerplate headers, and excessive whitespace. Target: > 0.70.
+
+**Metric 2 — Information Density:**
+```
+information_density = unique_concepts / total_sections
+```
+Where `unique_concepts` = count of distinct topics, terms, or instructions introduced. Measures whether each section contributes new information vs. repeating prior content. Target: > 2.0 concepts per section.
+
+**Metric 3 — Bloat Detection:**
+Identify sections where:
+- Section length > 3x the golden sample equivalent → BLOATED
+- Section length < 0.2x the golden sample equivalent → THIN
+- Section repeats > 30% of content from another section → REDUNDANT
+
+```
+bloat_score = 1 - (bloated_sections + thin_sections + redundant_sections) / total_sections
+```
+Clamped to [0, 1].
+
+**Performance Score:**
+```
+B3 = token_efficiency * 0.35 + normalize(information_density, 0, 4) * 0.35 + bloat_score * 0.30
+```
+Where `normalize(x, min, max)` clamps and scales x to [0, 1].
+
+**Display per-section metrics:**
+
+```
+Section                    Tokens   Concepts   Golden Ratio   Flag
+─────────────────────────  ──────── ────────── ──────────────  ──────────
+## Overview                 320      4          1.2x           OK
+## Protocol                 1840     12         0.8x           OK
+## Anti-Patterns            580      6          2.8x           BLOATED
+## Quick Start              95       2          0.3x           THIN
+## Dependencies             210      3          1.0x           OK
+```
+
+### Step 8: Aggregate & Gate
+
+**BENCHMARK_SCORE formula:**
+```
+BENCHMARK_SCORE = B0 * 0.30 + B1 * 0.35 + B2 * 0.15 + B3 * 0.20
+```
+
+**Weight rationale:**
+- B0 (Golden Comparison) at 0.30 — structural conformance is the primary benchmark signal
+- B1 (Test Suite) at 0.35 — deterministic correctness is the most reliable signal
+- B2 (Consistency) at 0.15 — stability matters but is a secondary signal
+- B3 (Performance) at 0.20 — efficiency matters for production artifacts
+
+**Gate:**
+- BENCHMARK_SCORE < 0.50 → **BLOCK** — artifact requires significant rework before evaluation
+- BENCHMARK_SCORE 0.50-0.70 → **WARN** — artifact has structural issues; proceed to TEST with caution
+- BENCHMARK_SCORE > 0.70 → **PASS** — artifact meets benchmark standards; ready for TEST
+
+Record `BENCHMARK_SCORE` for downstream consumption by `/bto-test` and `/bto`.
+
+---
+
+## Checkpoint
+
+```
+═══════════════════════════════════════════════════════
+CHECKPOINT: BENCHMARK Complete
+<promise>BTO_BENCHMARKED</promise>
+Artifact: [path]
+Type: [detected type]
+
+Layer B0 (Golden):      X.XX — section coverage, ordering, proportions
+Layer B1 (Test Suite):  X.XX — Y/Z tests passed
+Layer B2 (Consistency): X.XX — agreement across 3 probes
+Layer B3 (Performance): X.XX — token efficiency, density, bloat
+
+BENCHMARK SCORE: X.XX [PASS / WARN / BLOCK]
+
+• "ок" — proceed to TEST
+• "покажи детали [B0/B1/B2/B3]" — expand layer details
+• "пропусти тест" — skip TEST (if PASS)
+═══════════════════════════════════════════════════════
+```
+
+Wait for user confirmation.
+
+---
+
+## Modular Usage
+
+This command is also invoked internally by:
+- `/bto` — as a pre-flight step before TEST phase (if benchmark module is loaded)
+- `/bto-test` — optionally as a prerequisite gate (if user requests `benchmark` flag)
+
+The `BENCHMARK_SCORE` is available to downstream commands:
+- `/bto-test` may use it to calibrate Layer 1 expectations
+- `/bto-optimize` may use it to set a structural baseline floor
+
+## Critical Rules
+
+- Layer B0 and B1 are fully deterministic — no LLM calls, zero cost
+- Layer B2 uses haiku only — NEVER use sonnet or opus for consistency probes
+- Agent tool is REQUIRED for Layer B2 — do not run probes sequentially
+- Golden samples from `references/golden-samples.md` are the authoritative structural reference
+- If golden sample does not exist for the detected type → skip B0, set B0 = 0.50 (neutral), and log a warning
+- Report `BENCHMARK_SCORE` explicitly so downstream commands can consume it
+- BLOCK verdict at B0 or B1 halts the benchmark — do NOT proceed to subsequent layers
+- Layer B3 bloat detection uses golden sample proportions — without a golden sample, use absolute thresholds only
+- If "verbose" is in $ARGUMENTS, show expanded per-section diagnostics for all layers without prompting

package/templates/.claude/commands/harvest.md

@@ -2,66 +2,48 @@
 
 ## Использование
 ```
-/harvest [путь к директории исследования или "all"]
+/harvest [путь к директории или "all"] [only категория1,категория2]
 ```
 
 ## Аргумент
 $ARGUMENTS
 
-## Суть
-
-Систематический процесс извлечения и организации полезных знаний после завершения исследования. Не героическое усилие, а лёгкий процесс после каждого проекта.
-
-## Шаг 1 — Ревью с агентом
+## Скилл
 
-Просмотри указанную директорию исследования и TOOLKIT_HARVEST.md. Найди:
-1. Паттерны, которые можно обобщить
-2. Скиллы/команды/хуки, полезные за пределами этого проекта
-3. Ошибки и workaround-ы, которые стоит запомнить
-4. Удачные формулировки и шаблоны
-5. Инсайты о домене
-
-## Шаг 2 — Классификация
+```
+Read: .claude/skills/knowledge-extractor/SKILL.md
+```
 
-Каждая находка попадает в одну из корзин:
+Загрузи knowledge-extractor skill и следуй его Pipeline Protocol.
 
-| Категория | Что туда идёт | Пример |
-|-----------|--------------|--------|
-| skills/ | Новые или улучшенные SKILL.md | Лучший подход к CJM |
-| commands/ | Slash-команды для Claude Code | Новая фаза пайплайна |
-| rules/ | Правила и ограничения | "Не используй X потому что Y" |
-| templates/ | Шаблоны документов | Обновлённый шаблон архитектуры |
-| patterns/ | Архитектурные паттерны | Event sourcing для AI pipeline |
-| snippets/ | Готовые куски кода | Универсальный CJM renderer |
+## Парсинг аргументов
 
-## Шаг 3 — Деконтекстуализация
+1. **Путь:** Первый аргумент — путь к директории исследования или `"all"` для всех директорий в `researches/`
+2. **Scope filter:** Если после пути есть `only X,Y` — передай как `{SCOPE_FILTER}` в skill
+   - Допустимые значения: `skills`, `commands`, `hooks`, `rules`, `templates`, `patterns`, `snippets`
+   - Множественные через запятую: `only rules,templates`
+3. Если аргументов нет — запроси путь у пользователя
 
-Перед переносом в тулкит:
-1. **Деконтекстуализировать** — убрать привязки к конкретному проекту
-2. **Документировать** — когда использовать, когда нет, предусловия
-3. **Версионировать** — пометить что изменилось и почему
+## Примеры
 
-Каждый артефакт должен содержать:
-```markdown
-## Maturity: 🟡 Beta / 🟢 Stable
-## Used in: [список проектов]
-## Last updated: [дата]
-## Changelog:
-- v1: начальная версия из [проект]
+```
+/harvest researches/bank-kc-automation/          ← полный harvest одной директории
+/harvest researches/bank-kc-automation/ only patterns  ← только паттерны
+/harvest all                                     ← все исследования
+/harvest all only rules,templates                ← все исследования, только правила и шаблоны
+/harvest features/add-user-auth/                 ← harvest фичи (не только исследования)
 ```
 
-## Шаг 4 — Обновление TOOLKIT_HARVEST.md
-
-Обнови корневой `TOOLKIT_HARVEST.md` с новыми находками.
+## Параллелизация
 
-## Что НЕ тащить
+Если путь = `"all"`:
+1. Получи список всех директорий в `researches/`
+2. Для каждой директории запусти отдельную harvest сессию
+3. Каждая сессия создаёт свой findings JSON и проходит полный pipeline
+4. По завершении всех сессий — объедини отчёты
 
-- Код, который работает только в контексте конкретного домена
-- Паттерны, использованные один раз без уверенности в качестве
-- Workaround-ы для конкретных багов библиотек (устаревают)
+## Суть
 
-## Параллелизация
+Систематический процесс извлечения и организации полезных знаний после завершения проекта. Использует 5 параллельных агентов-экстракторов, 7-категорийную классификацию, 8 блокирующих quality gates, и автоматическое размещение артефактов.
 
-Если `$ARGUMENTS` = "all", запусти агентов параллельно для каждой директории в `researches/`:
-- Каждый агент ревьюит свою директорию
-- Результаты синтезируются в единый TOOLKIT_HARVEST.md
+Pipeline: Extract (5 agents) → Classify (7 categories) → User Checkpoint → Gate (8 checks) → Integrate (auto-place)

package/templates/.claude/rules/trust-tiers.md

@@ -20,6 +20,7 @@
 | presentation-storyteller | 1 | Structured | SKILL.md + references/ |
 | reverse-engineering-unicorn | 1 | Structured | SKILL.md + modules/ + references/ + examples/ |
 | bto | 1 | Structured | SKILL.md + modules/ + references/ + examples/ |
+| knowledge-extractor | 2 | Validated | /bto-test Layer 2 score 7.5, optimized 2026-03-03 |
 
 ## Tier Enforcement