@dzhechkov/keysarium 1.3.0 → 1.4.0

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 |

package/templates/.claude/skills/knowledge-extractor/modules/01-extract.md

@@ -0,0 +1,188 @@
+# Extract Module — Parallel Knowledge Extraction
+
+## Purpose
+
+Spawn 5 focused extractor agents to scan a project directory through different lenses, collecting reusable knowledge findings with confidence scores.
+
+## Input
+
+- `{TARGET_PATH}` — directory to scan (e.g., `researches/bank-kc-automation/`)
+- `{SCOPE_FILTER}` — optional list of lenses to activate (null = all 5)
+- `{MEMORY_PATTERNS}` — historical patterns from memory_query() (may be empty)
+- `{SESSION_ID}` — harvest session identifier
+
+## Protocol
+
+### Step 1: Inventory Target Directory
+
+List all files in `{TARGET_PATH}`. Build a file manifest with paths and sizes.
+Skip binary files, images, and files > 100KB.
+
+### Step 2: Determine Active Agents
+
+If `{SCOPE_FILTER}` is set, map categories to lenses:
+
+| Requested Category | Agent Lens to Spawn |
+|-------------------|---------------------|
+| patterns | extractor-patterns |
+| commands | extractor-commands |
+| hooks | extractor-commands (shared) |
+| rules | extractor-rules |
+| templates | extractor-templates |
+| snippets | extractor-snippets |
+| skills | ALL agents (cross-cutting) |
+
+If `{SCOPE_FILTER}` is null, spawn all 5 agents.
+
+### Step 3: Spawn Extractor Agents
+
+Spawn selected agents in parallel using the Agent tool:
+
+```
+Agent(
+  subagent_type="general-purpose",
+  model="sonnet",
+  description="Harvest Extractor — {LENS_NAME}",
+  prompt="""
+    You are a knowledge extraction agent with a focused lens: {LENS_DESCRIPTION}.
+
+    ## Your Task
+    Scan the following project files and extract reusable knowledge through your lens.
+    For each finding, provide:
+    1. A short descriptive title (3-8 words)
+    2. Content: the reusable knowledge (decontextualized where possible)
+    3. "When to use" guidance (1-2 sentences)
+    4. "When NOT to use" guidance (1-2 sentences)
+    5. A concrete example of usage
+    6. Reusability confidence (0.0 to 1.0):
+       - 0.9-1.0: Universal, works in any project
+       - 0.7-0.89: Works in most similar projects
+       - 0.5-0.69: Works in some contexts
+       - < 0.5: Probably too project-specific
+    7. Suggested maturity: alpha (first time seen) or beta (if evidence of reuse)
+
+    ## Project Files
+    Read the following directory: {TARGET_PATH}
+
+    ## Historical Patterns (from previous harvests)
+    {MEMORY_PATTERNS_OR_NONE}
+
+    Avoid extracting findings that overlap with these historical patterns.
+
+    ## Extraction Rules
+    - Extract ONLY genuinely reusable knowledge
+    - DO NOT extract project-specific implementation details
+    - DO NOT extract trivial or obvious patterns
+    - Each finding must be independently useful outside this project
+    - Prefer actionable knowledge over abstract observations
+    - If in doubt about reusability, include it with a lower confidence score
+
+    ## Output Format
+    Return a numbered list of findings in this exact format:
+
+    ### Finding 1
+    **Title:** [short title]
+    **Confidence:** [0.0-1.0]
+    **Maturity:** [alpha|beta]
+    **Content:** [the reusable knowledge]
+    **When to use:** [guidance]
+    **When NOT to use:** [anti-guidance]
+    **Example:** [concrete example]
+
+    ### Finding 2
+    ...
+  """
+)
+```
+
+### Step 4: Handle Agent Failures
+
+If any extractor agent fails, times out, or returns malformed output:
+
+1. **Partial success:** Proceed with results from successful agents. Do NOT block the entire pipeline.
+2. **Log failures:** Record which lenses failed and why:
+   ```
+   ⚠️ Extractor agent failed: extractor-snippets (timeout after 120s)
+   Proceeding with 4/5 lenses. Snippets will not be harvested.
+   ```
+3. **Surface in report:** Add failed lenses to the harvest report's "Coverage Gaps" section.
+4. **Retry option:** Offer the user: `"повтори snippets"` — retry the failed lens only.
+5. **Malformed output:** If an agent returns output that cannot be parsed into the Finding format, discard that agent's results and log: `"Extractor {lens} returned unparseable output — discarded."`
+6. **Zero findings:** If an agent returns no findings, this is normal (not all lenses find relevant content). Log: `"Extractor {lens}: 0 findings (no relevant content detected)."`
+
+### Step 5: Report Skipped Files
+
+Before merging, surface any files that were skipped during inventory:
+
+```
+📋 File inventory: {total_files} files scanned, {skipped_count} skipped
+Skipped: {file1} (112KB, exceeds 100KB limit), {file2} (binary)
+```
+
+Include this in the harvest report under "Coverage Gaps" so the user knows what was NOT examined.
+
+### Step 6: Merge Results
+
+After all agents complete (or after handling failures):
+
+1. Collect all findings from all agents
+2. Assign sequential numbers starting from 1 (global numbering across all agents)
+3. Tag each finding with its source lens
+4. Set initial status to `raw`
+5. Write to findings JSON file at `.keysarium/harvest/findings-{SESSION_ID}.json`
+
+### 5 Agent Lens Descriptions
+
+| Agent | Lens Description |
+|-------|-----------------|
+| extractor-patterns | Architecture patterns, design patterns, agent topologies, data flow patterns, orchestration strategies, parallelism approaches. Look for structural solutions that could be applied to other systems. |
+| extractor-commands | CLI commands, scripts, pipeline stages, automation workflows, slash commands, build processes. Look for reusable command patterns and workflow automations. |
+| extractor-rules | Constraints, quality gates, anti-patterns, domain rules, naming conventions, regulatory requirements, lessons learned. Look for guardrails and restrictions that prevent mistakes. |
+| extractor-templates | Document structures, config file formats, diagram templates, report formats, checklist templates. Look for reusable document and configuration scaffolding. |
+| extractor-snippets | Reusable code fragments, utility functions, React components, bash one-liners, prompt templates, hook implementations. Look for copy-paste-ready code blocks. |
+
+## Output Format
+
+The findings JSON file structure:
+
+```json
+{
+  "session_id": "{SESSION_ID}",
+  "status": "extracting",
+  "target_paths": ["{TARGET_PATH}"],
+  "scope_filter": null,
+  "created_at": "ISO-8601",
+  "next_number": 16,
+  "extractors_spawned": ["patterns", "commands", "rules", "templates", "snippets"],
+  "findings": {
+    "1": {
+      "number": 1,
+      "title": "Agent Swarm Topology",
+      "content": "...",
+      "when_to_use": "...",
+      "when_not_to_use": "...",
+      "example": "...",
+      "confidence": 0.85,
+      "maturity": "alpha",
+      "source_lens": "patterns",
+      "category": null,
+      "status": "raw",
+      "gate_results": {},
+      "gate_overrides": [],
+      "merged_from": null
+    }
+  }
+}
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Agent extracts trivial findings | Findings like "use git for version control" | Prompt emphasizes non-obvious, actionable knowledge |
+| Agent reads files outside target | File paths outside {TARGET_PATH} | Prompt constrains to target directory only |
+| Duplicate findings across agents | Two agents extract the same pattern | Handled by Module 02 (dedup), not here |
+| Agent returns unstructured text | Missing required fields in output | Strict output format in prompt; orchestrator validates |
+| All findings have confidence 0.9+ | Agent is not being self-critical | Prompt calibration: explain the confidence scale |
+| Agent timeout with no fallback | Pipeline stalls waiting for failed agent | Use Step 4 failure protocol: proceed with partial results |
+| Large files silently skipped | User unaware of coverage gaps | Step 5 surfaces skipped files; harvest report includes coverage gaps |

package/templates/.claude/skills/knowledge-extractor/modules/02-classify.md

@@ -0,0 +1,99 @@
+# Classify Module — 7-Category Classification and Deduplication
+
+## Purpose
+
+Assign each raw finding to one of 7 categories, deduplicate across agents, and cross-reference against existing toolkit entries.
+
+## Input
+
+- Findings JSON file (from Module 01, status: `extracting` → set to `classifying`)
+- `TOOLKIT_HARVEST.md` — existing entries to check for duplicates
+- `references/artifact-categories.md` — category definitions and destination mapping
+
+## Protocol
+
+### Step 1: Load and Validate
+
+1. Read findings JSON file
+2. Verify all findings have status `raw`
+3. Set session status to `classifying`
+4. Read `references/artifact-categories.md` for category definitions
+
+### Step 2: Classify Each Finding
+
+For each finding, assign a category based on content analysis:
+
+| Category | Classification Signals |
+|----------|----------------------|
+| skills | Multi-step methodology, complete workflow, orchestrator + modules pattern |
+| commands | Starts with `/` or describes a CLI invocation, has arguments/parameters |
+| hooks | Triggered by an event, pre/post pattern, automation on lifecycle events |
+| rules | Contains "must", "never", "always", constraints, anti-pattern tables |
+| templates | Document skeleton, config file format, placeholder structure `{VAR}` |
+| patterns | Architectural approach, design strategy, topology, reusable structure |
+| snippets | Code block, function, component, < 50 lines, copy-paste ready |
+
+**Tie-breaking rules:**
+- If a finding could be both `patterns` and `skills` → prefer `patterns` unless it has modules/sub-components
+- If a finding could be both `rules` and `patterns` → prefer `rules` if it's primarily a constraint
+- If a finding could be both `templates` and `snippets` → prefer `templates` if it has placeholders, `snippets` if it's code
+
+### Step 3: Deduplicate
+
+**Cross-agent dedup:** Compare all findings pairwise within the session using this algorithm:
+
+1. **Title similarity:** Normalize titles (lowercase, strip punctuation, remove stop words). Compute token overlap ratio: `shared_tokens / max(tokens_A, tokens_B)`.
+2. **Content similarity:** Extract the first 3 non-empty lines of each finding's `content` field. Compute 3-gram set overlap (Jaccard index): `|A ∩ B| / |A ∪ B|`.
+3. **Combined score:** `similarity = title_weight * title_sim + content_weight * content_sim` where `title_weight = 0.4`, `content_weight = 0.6`.
+4. **Threshold:** If `similarity >= 0.80` → duplicate. Keep the finding with higher confidence. Set the other's status to `removed`.
+5. Log: `"Dedup: #N removed (duplicate of #M, similarity: {score})"`
+
+Note: Since an LLM is performing this comparison (not a deterministic function), the algorithm above provides guidance for consistent judgment. The orchestrator should evaluate each pair and apply the threshold consistently.
+
+**Cross-toolkit dedup:** Compare findings against existing `TOOLKIT_HARVEST.md` entries:
+1. For each finding, scan TOOLKIT_HARVEST.md section headings and first paragraphs.
+2. If a finding's title matches an existing entry name (exact or near-match after normalization):
+   - Set finding's `duplicate_of` field to the existing entry name
+   - Flag for gate G6 (will be evaluated in Module 03)
+3. Near-duplicate range (0.70-0.85 similarity): propose a MERGE instead of flagging as duplicate.
+
+### Step 4: Cross-Reference
+
+For each classified finding, check if it references or depends on existing toolkit items:
+- If finding mentions a skill name → add cross-reference link
+- If finding extends an existing pattern → note the relationship
+- Record cross-references in the finding's metadata
+
+### Step 5: Write Results
+
+1. Update each finding in the JSON file with: `category`, `status: "classified"`
+2. Update session status
+3. Return classification summary for display
+
+## Output Format
+
+The orchestrator displays classified findings grouped by category:
+
+```
+## patterns ({N} 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 ({N} items)
+#2  [0.91] Domain Detection Rule — auto-detect domain from keywords
+#7  [0.65] Regulatory Constraint — ФЗ-152 data isolation requirement
+
+## commands ({N} items)
+...
+
+## Removed by dedup: #5 (duplicate of #1), #9 (duplicate of #3)
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Everything classified as "patterns" | > 50% of findings in one category | Re-evaluate with stricter classification signals |
+| Aggressive dedup removes valid findings | High similarity but different use cases | Compare "When to use" sections, not just content |
+| Missing cross-references | Finding extends existing tool but no link | Check TOOLKIT_HARVEST.md entry names explicitly |
+| Category mismatch with source lens | extractor-rules finding classified as pattern | Lens is a hint, not a binding — classify on content |

package/templates/.claude/skills/knowledge-extractor/modules/03-gate.md

@@ -0,0 +1,150 @@
+# Gate Module — 8 Quality Gates with 2-Pass Evaluation
+
+## Purpose
+
+Evaluate each active finding against 8 quality gates using a two-pass approach: deterministic checks first (zero LLM cost), then semantic checks via haiku agent. Set finding status to `approved` or `blocked`.
+
+## Input
+
+- Findings JSON file (from user checkpoint, active findings only)
+- `references/quality-gates.md` — gate definitions, pass criteria, failure messages
+
+## Protocol
+
+### Step 1: Load Gate Definitions
+
+```
+Read: references/quality-gates.md
+```
+
+Load all 8 gate definitions with their type (deterministic/semantic) and pass criteria.
+
+### Step 2: Filter Active Findings
+
+From the findings JSON, select only findings with status `classified` (not `removed` or `merged`).
+These are the findings that survived the user checkpoint.
+
+### Step 3: Pass 1 — Deterministic Gates
+
+For each active finding, evaluate deterministic gates. These are simple checks that require no LLM:
+
+| Gate | Check Logic |
+|------|------------|
+| G1 | `finding.when_to_use` exists AND length > 10 characters |
+| G2 | `finding.when_not_to_use` exists AND length > 10 characters |
+| G5 | `finding.confidence >= 0.5` |
+| G6 | `finding.duplicate_of` is null OR empty (set by Module 02) |
+| G7 | `finding.maturity` is one of: `alpha`, `beta`, `stable` |
+
+For each gate, record the result:
+```json
+{
+  "gate_id": "G1",
+  "passed": true,
+  "evaluation_pass": "deterministic",
+  "reason": null
+}
+```
+
+If any deterministic gate fails, record the failure reason from `quality-gates.md`.
+
+### Step 4: Pass 2 — Semantic Gates
+
+For findings that passed all deterministic gates (or for all findings if you want complete gate data), evaluate semantic gates using a haiku agent:
+
+```
+Agent(
+  subagent_type="general-purpose",
+  model="haiku",
+  description="Harvest Gate Evaluator — semantic gates",
+  prompt="""
+    You are a quality gate evaluator. For each finding below, evaluate 3 semantic gates.
+    Be strict but fair. Err on the side of blocking rather than passing questionable findings.
+
+    ## Gates to Evaluate
+
+    **G3 — Decontextualized:**
+    Check if the finding contains project-specific references: variable names, file paths,
+    company names, dates, slugs, or any hardcoded values tied to the source project.
+    PASS if the finding is generic and reusable as-is.
+    FAIL if any project-specific detail remains.
+
+    **G4 — Concrete Example:**
+    Check if the finding includes at least one concrete, actionable example.
+    The example must show actual usage, not just describe it abstractly.
+    PASS if there is a real example with specifics.
+    FAIL if the example is vague, abstract, or missing.
+
+    **G8 — Brutal Honesty Review:**
+    Ask yourself: "Would a senior engineer actually find this useful in a different project?"
+    PASS only if the answer is genuinely yes — the finding adds real value.
+    FAIL if the finding is obvious, trivial, or too niche to be broadly useful.
+
+    ## Findings to Evaluate
+
+    {FINDINGS_LIST}
+
+    ## Required Output Format
+
+    For each finding, return:
+
+    Finding #N:
+    - G3: PASS/FAIL — [reason]
+    - G4: PASS/FAIL — [reason]
+    - G8: PASS/FAIL — [reason]
+  """
+)
+```
+
+### Step 5: Set Approval Status
+
+For each finding:
+- If ALL 8 gates passed → status = `approved`
+- If ANY gate failed → status = `blocked`, record failing gate IDs
+
+Write results to findings JSON.
+
+### Step 6: Report Blocked Findings
+
+The orchestrator displays blocked findings to the user:
+
+```
+✅ APPROVED: {N} findings passed all gates
+
+⚠️ BLOCKED: {M} findings failed quality gates:
+  #7  — G3 (project-specific references remain: mentions "bank-kc-automation")
+  #12 — G5 (confidence 0.35 < 0.5 threshold)
+  #14 — G4, G8 (no concrete example; fails brutal-honesty review)
+
+Commands:
+• "пропусти GN для #X"  — override specific gate for specific finding
+• "ок"                   — accept blocks, proceed with approved only
+```
+
+### Step 7: Apply Overrides (if any)
+
+If user overrides a gate:
+1. Add gate ID to finding's `gate_overrides` array
+2. Recalculate: if all non-overridden gates pass → status = `approved`
+3. Log override for audit trail
+
+## Override Protocol
+
+User command: `"пропусти G3 для #7"` (override G3 for finding #7)
+
+Validation:
+- Finding #7 must exist and be `blocked`
+- G3 must be one of the failing gates for finding #7
+- **G6 (Not Duplicate) and G8 (Brutal Honesty) CANNOT be overridden** — reject override attempts for these gates
+- Record the override with timestamp
+
+Multiple overrides: `"пропусти G3,G4 для #14"` — override multiple gates at once.
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| All findings pass all gates | 100% pass rate | Haiku semantic evaluator may be too lenient — add calibration examples |
+| Gate G8 blocks everything | > 80% fail on G8 | Review extraction quality — if findings are genuinely weak, that's correct |
+| Overriding all blocked gates | User overrides every block | Advisory: suggest improving extraction rather than overriding all gates |
+| Semantic evaluator contradicts itself | G3 passes but content has project refs | Log discrepancy, flag for human review |