@dzhechkov/keysarium 1.2.0 → 1.4.0

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
 

package/templates/.claude/skills/knowledge-extractor/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: knowledge-extractor
+description: >
+  Multi-agent knowledge harvesting system that extracts reusable patterns, commands,
+  rules, templates, and snippets from any project directory. Uses 5 parallel extractor
+  agents, 7-category classification, 8 blocking quality gates, and auto-placement.
+  Triggers on "harvest", "extract knowledge", "извлеки знания", "/harvest".
+trust_tier: 2
+trust_tier_label: "Validated"
+bto_score: 7.5
+bto_date: "2026-03-03"
+trust_tier_path: "Run /bto-test, score >= 8.5 + eval tests for Tier 3"
+---
+
+# Knowledge Extractor
+
+> Domain-agnostic multi-agent system for extracting, classifying, gating, and placing
+> reusable knowledge from completed projects into the toolkit.
+
+## When To Activate
+
+Trigger on:
+- `/harvest [path]` or `/harvest all`
+- "extract knowledge from [path]"
+- "извлеки знания из [path]"
+- "harvest patterns from [project]"
+- "что можно переиспользовать из [project]"
+
+## What You Get
+
+After a successful harvest session:
+- **Findings JSON** — structured extraction results at `.keysarium/harvest/findings-{SESSION_ID}.json`
+- **Placed artifacts** — skills, commands, and rules placed in `.claude/skills/`, `.claude/commands/`, `.claude/rules/`
+- **TOOLKIT_HARVEST.md** — updated with new patterns, templates, snippets, and hooks
+- **Harvest report** — session summary with metrics (extracted → approved → placed counts, gate pass rates)
+- **Memory record** — reward data stored via `memory_store()` for future session optimization
+
+## Architecture
+
+```
+.claude/skills/knowledge-extractor/
+├── SKILL.md                              ← This file (orchestrator)
+├── modules/
+│   ├── 01-extract.md                     ← 5 parallel extractor agents
+│   ├── 02-classify.md                    ← 7-category classification + dedup
+│   ├── 03-gate.md                        ← 8 quality gates (2-pass)
+│   └── 04-integrate.md                   ← Auto-placement + harvest report
+├── references/
+│   ├── quality-gates.md                  ← Gate definitions (G1-G8)
+│   ├── artifact-categories.md            ← 7 categories with destinations
+│   └── maturity-model.md                 ← Alpha → Beta → Stable
+└── templates/
+    ├── artifact-card.md                  ← Per-finding output template
+    └── harvest-report.md                 ← Session summary template
+```
+
+## Modules
+
+| Module | Purpose | Agents | Model |
+|--------|---------|--------|-------|
+| 01-extract | Scan project via 5 focused lenses | 5 parallel | sonnet |
+| 02-classify | Assign categories, deduplicate, cross-ref | 0 (inline) | — |
+| 03-gate | Evaluate 8 quality gates in 2 passes | 1 (semantic) | haiku |
+| 04-integrate | Place artifacts, generate report | 0 (inline) | — |
+
+## Pipeline Protocol
+
+### Step 0: Initialize Session
+
+1. Parse arguments: `{TARGET_PATH}` (directory or "all"), `{SCOPE_FILTER}` (optional `only X,Y`)
+2. **Resolve target path:**
+   - If `{TARGET_PATH}` is a specific directory → validate it exists, set `{slug}` = directory basename
+   - If `{TARGET_PATH}` is `"all"` → list all subdirectories in `researches/`. For each directory, run a separate harvest session (each gets its own findings JSON, session ID, and pipeline run). Merge reports at the end.
+   - If `{TARGET_PATH}` does not exist → report error and stop
+3. **Resolve domain:** If running inside a `/casarium` pipeline, inherit `{domain}` from Phase 0 discovery. If standalone, detect domain from file content keywords (banking/retail/enterprise/healthcare). If unable to detect, set `{domain}` = `"unknown"`.
+4. Generate session ID: `{slug}-{YYYYMMDDHHmmss}`
+5. If `TOOLKIT_HARVEST.md` does not exist at repo root → create it with a standard skeleton (title + empty section headers for each category).
+6. Call `memory_query({phase: "harvest", domain, slug, skill: "knowledge-extractor"})`
+7. Log loaded patterns count
+
+### Step 1: Extract (Module 01)
+
+```
+Read: modules/01-extract.md
+```
+
+Spawn 5 parallel extractor agents (sonnet), each with a focused lens:
+
+| Agent | Lens | Seeks |
+|-------|------|-------|
+| extractor-patterns | patterns | Architecture patterns, design patterns, agent topologies |
+| extractor-commands | commands | Scripts, CLI workflows, pipeline stages, automation |
+| extractor-rules | rules | Constraints, anti-patterns, lessons learned, domain rules |
+| extractor-templates | templates | Document structures, config templates, diagram templates |
+| extractor-snippets | snippets | Reusable code fragments, hooks, utility functions |
+
+Each agent returns numbered findings with reusability confidence (0.0-1.0).
+Orchestrator merges all findings into a single numbered list and writes to JSON:
+`.keysarium/harvest/findings-{SESSION_ID}.json`
+
+**Scope filtering:** If `{SCOPE_FILTER}` is set, only spawn matching agents. See mapping in `references/artifact-categories.md`.
+
+### Step 2: Classify (Module 02)
+
+```
+Read: modules/02-classify.md
+Read: references/artifact-categories.md
+```
+
+1. Read findings from JSON file
+2. Assign each finding to one of 7 categories
+3. Deduplicate: check content similarity across findings and against TOOLKIT_HARVEST.md
+4. Cross-reference: link findings that reference existing skills/commands
+5. Write classified findings back to JSON
+
+### Step 3: User Checkpoint (Interactive)
+
+Display all findings grouped by category as a numbered list:
+
+```
+═══════════════════════════════════════════════════════
+📋 HARVEST FINDINGS: {N} items extracted
+
+## patterns (K items)
+#1  [0.85] Agent Swarm Topology — parallel agents with merge pattern
+#4  [0.72] Event-Driven Pipeline — phase-to-phase data flow via files
+
+## rules (M items)
+#2  [0.91] Domain Detection Rule — auto-detect domain from keywords
+#7  [0.65] Regulatory Constraint — ФЗ-152 data isolation requirement
+
+## snippets (P items)
+#3  [0.78] CJM Renderer — universal React component for CJM display
+...
+
+Commands:
+• "убери #N"                    — remove finding
+• "переклассифицируй #N в X"   — reclassify to category X
+• "доработай #N"                — expand/improve finding
+• "объедини #N и #M"            — merge two findings
+• "покажи только X"             — filter by category
+• "ок"                          — proceed to quality gates
+═══════════════════════════════════════════════════════
+```
+
+Apply user mutations to JSON file. Numbers are stable (removed items leave gaps).
+Loop until user says "ок".
+
+### Step 4: Gate (Module 03)
+
+```
+Read: modules/03-gate.md
+Read: references/quality-gates.md
+```
+
+Evaluate each active finding against 8 quality gates in 2 passes:
+
+**Pass 1 — Deterministic (zero LLM cost):**
+- G1: Has "When to use" section
+- G2: Has "When NOT to use" section
+- G5: Reusability confidence >= 0.5
+- G6: Not a duplicate of existing toolkit entry
+- G7: Has maturity label (alpha/beta/stable)
+
+**Pass 2 — Semantic (haiku agent):**
+- G3: Properly decontextualized (no project-specific refs)
+- G4: Has at least one concrete example
+- G8: Passes brutal-honesty review (self-critical assessment)
+
+Findings passing all gates → status `approved`.
+Findings failing any gate → status `blocked` with gate IDs.
+
+Display blocked findings and allow overrides:
+```
+⚠️ BLOCKED: #7 — failed G3 (project-specific references remain)
+• "пропусти G3 для #7" — override gate
+• "ок" — accept blocks, proceed with approved only
+```
+
+### Step 5: Integrate (Module 04)
+
+```
+Read: modules/04-integrate.md
+Read: templates/artifact-card.md
+Read: templates/harvest-report.md
+```
+
+1. Render artifact cards for each approved finding
+2. Auto-place by category:
+   - `skills` → create `.claude/skills/<name>/SKILL.md` (skeleton)
+   - `commands` → create `.claude/commands/<name>.md`
+   - `hooks` → document in TOOLKIT_HARVEST.md (hooks section)
+   - `rules` → create `.claude/rules/<name>.md`
+   - `templates` → document in TOOLKIT_HARVEST.md (templates section)
+   - `patterns` → document in TOOLKIT_HARVEST.md (patterns section)
+   - `snippets` → document in TOOLKIT_HARVEST.md (snippets section)
+3. Update TOOLKIT_HARVEST.md "Обработанные проекты" table
+4. Generate harvest report
+5. Call `memory_store()` with harvest results and user reward
+6. Update `.keysarium/insights/trigger-state.json` (case_completion event)
+7. Clean up findings JSON file
+
+## Scope Filtering
+
+The `only` keyword filters which extractor agents are spawned:
+
+```
+/harvest path/                      → all 5 agents
+/harvest path/ only patterns        → extractor-patterns only
+/harvest path/ only rules,templates → extractor-rules + extractor-templates
+/harvest all only snippets          → extractor-snippets for each directory
+```
+
+Category-to-agent mapping (see `references/artifact-categories.md`):
+- patterns → extractor-patterns
+- commands → extractor-commands
+- hooks → extractor-commands (shared lens)
+- rules → extractor-rules
+- templates → extractor-templates
+- snippets → extractor-snippets
+- skills → all agents (skills are cross-cutting)
+
+## Integration Points
+
+| System | When | Operation |
+|--------|------|-----------|
+| memory_query() | Pipeline start | Load historical harvest patterns |
+| memory_store() | After user checkpoint | Store harvest reward data |
+| brain-export | N/A (passive) | Findings JSON is brain-compatible schema |
+| BTO | Post-harvest | Placed skills can be evaluated via `/bto-test` |
+| dream cycles | Pipeline end | Update trigger-state.json |
+| /harvest command | Entry point | Thin wrapper loads this skill |
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Extracting project-specific details | Finding contains project names, slugs, dates | Decontextualize: replace specifics with generic placeholders |
+| Duplicate extraction | content_hash matches existing TOOLKIT_HARVEST.md entry | Skip or merge; gate G6 blocks duplicates |
+| Extracting from incomplete phases | Artifact lacks promise tag or checkpoint | Only harvest from completed projects |
+| Over-classifying snippets as patterns | Single-use code without abstraction | Require reuse evidence before promoting to pattern |
+| Under-specifying maturity | All findings marked "stable" on first run | First extraction is always "alpha" or "beta" |
+| Skipping user checkpoint | Proceeding to gates without user review | BLOCK — user checkpoint is mandatory |
+| Running all agents when scope is filtered | `only patterns` but 5 agents spawned | Check SCOPE_FILTER before spawning |
+
+## Dependencies
+
+| Resource | Path | Purpose |
+|----------|------|---------|
+| quality-gates.md | references/quality-gates.md | Gate definitions for Module 03 |
+| artifact-categories.md | references/artifact-categories.md | 7-category taxonomy |
+| maturity-model.md | references/maturity-model.md | Alpha/Beta/Stable criteria |
+| artifact-card.md | templates/artifact-card.md | Per-finding output format |
+| harvest-report.md | templates/harvest-report.md | Session report format |