@dzhechkov/keysarium 1.1.2 → 1.2.0

package/templates/docs/keysarium/02-admin-guide.md

@@ -14,6 +14,8 @@
 6. [Мониторинг](#6-мониторинг)
 7. [Кастомизация пайплайна](#7-кастомизация-пайплайна)
 8. [Бэкап и восстановление](#8-бэкап-и-восстановление)
+9. [Governance Shards](#9-governance-shards)
+10. [Trust Tiers](#10-trust-tiers)
 
 ---
 
@@ -31,6 +33,8 @@
 | presentation-storyteller | `.claude/skills/presentation-storyteller/` | Презентации со storytelling | Phase 5 |
 | problem-solver-enhanced | `.claude/skills/problem-solver-enhanced/` | Решение проблем (TRIZ + Game Theory) | Phase 3 |
 | reverse-engineering-unicorn | `.claude/skills/reverse-engineering-unicorn/` | Reverse engineering компаний | Phase 0, Phase 2.5 |
+| bto | `.claude/skills/bto/` | Build-Test-Optimize: мульти-агентная оценка | BTO pipeline |
+| feature-adr | `.claude/skills/feature-adr/` | Adaptive Feature Development (9 шагов) | /feature-adr |
 
 ### 1.2. Структура директории скилла
 
@@ -242,6 +246,18 @@ rm -rf researches/_test_skill/
 | `/architecture-phase` | `architecture-phase.md` | Phase 4: Architecture |
 | `/presentation` | `presentation.md` | Phase 5: Presentation |
 | `/harvest` | `harvest.md` | Извлечение знаний |
+| `/brain-export` | `brain-export.md` | Экспорт портативных знаний |
+| `/brain-import` | `brain-import.md` | Импорт знаний из другого проекта |
+| `/init-platform` | `init-platform.md` | Генерация конфигов для Cursor/OpenCode/Copilot |
+| `/workers` | `workers.md` | Управление фоновыми воркерами |
+| `/dream` | `dream.md` | Dream Cycles (анализ паттернов) |
+| `/learning-stats` | `learning-stats.md` | Reward learning аналитика |
+| `/verify-chain` | `verify-chain.md` | Верификация witness chain |
+| `/feature-adr` | `feature-adr.md` | Adaptive Feature Development pipeline |
+| `/bto` | `bto.md` | Полный BTO цикл (Build-Test-Optimize) |
+| `/bto-build` | `bto-build.md` | Генерация скиллов/команд |
+| `/bto-test` | `bto-test.md` | Мульти-агентная оценка |
+| `/bto-optimize` | `bto-optimize.md` | Эволюционная оптимизация |
 
 ### 2.2. Формат файла команды
 
@@ -380,6 +396,15 @@ CHECKPOINT X: [Phase Name] Complete
 | `file-conventions.md` | Конвенции именования файлов и директорий |
 | `modular-reuse.md` | Правила модульного переиспользования скиллов и команд |
 | `research-quality.md` | Требования к качеству research (PARANOID mode) |
+| `witness-chain.md` | Witness chain integration: SHA-256 хеширование артефактов |
+| `reward-learning.md` | Reward-calibrated learning: memory_query/memory_store протокол |
+| `background-workers.md` | Background workers: isolation, model routing, concurrency limits |
+| `dream-cycles.md` | Dream cycles: auto-triggers, insight application, retention |
+| `model-routing.md` | 3-tier model routing enforcement (haiku/sonnet/opus) |
+| `trust-tiers.md` | Trust tier system для скиллов (Tier 0-3) |
+| `bto-quality-gates.md` | BTO quality gates: layer architecture, judge panel, optimization delta |
+| `feedback-loops.md` | Cross-phase feedback loops and variable registry |
+| `feature-adr-conventions.md` | Feature ADR conventions: output directory, slugs, tiers |
 
 ### 3.2. Добавление нового правила
 
@@ -1099,6 +1124,149 @@ rm -rf researches/<slug>/
 
 ---
 
+## 9. Governance Shards
+
+### 9.1. Что такое shards
+
+Governance shards -- это специализированные файлы конфигурации для каждой фазы пайплайна. Они хранятся в `.claude/shards/` и решают проблему контекстного дрейфа (context drift) при длинных сессиях: агент перечитывает shard перед началом каждой фазы, получая актуальные правила именно для этой фазы.
+
+Каждый shard содержит:
+- **time budget** -- отведённый процент времени на фазу
+- **skill to load** -- скилл, который нужно загрузить
+- **prerequisites** -- какие артефакты и promises должны существовать
+- **quality gates** -- критерии качества для прохождения checkpoint
+- **promise tag** -- тег семантического завершения фазы
+
+### 9.2. Текущие shards
+
+| Файл | Фаза | Promise Tag |
+|------|------|-------------|
+| `phase-0-discovery.shard.md` | Phase 0: Product Discovery | `DISCOVERY_COMPLETE` |
+| `phase-1-explore.shard.md` | Phase 1: Explore | `CASE_EXPLORED` |
+| `phase-2-research.shard.md` | Phase 2: Research | `RESEARCH_PARANOID_PASSED` |
+| `phase-25-cjm.shard.md` | Phase 2.5: CJM Prototype | `CJM_VALIDATED` |
+| `phase-3-solve.shard.md` | Phase 3: Solve | `SOLUTION_DESIGNED` |
+| `phase-4-architecture.shard.md` | Phase 4: Architecture | `ARCHITECTURE_DEFINED` |
+| `phase-5-presentation.shard.md` | Phase 5: Presentation | `PRESENTATION_READY` |
+| `bto-evaluation.shard.md` | BTO: оценка скилла/артефакта | `BTO_LAYER2_SCORED` |
+| `feature-adr.shard.md` | Feature ADR: адаптивная разработка | (per-step promises) |
+
+### 9.3. Добавление нового shard
+
+При создании новой фазы пайплайна создайте соответствующий shard:
+
+```bash
+touch .claude/shards/phase-35-usability.shard.md
+```
+
+Минимальная структура shard:
+
+```markdown
+# Phase 3.5: Usability Testing — Governance Shard
+
+## Time Budget
+5% от общего времени кейса
+
+## Skill to Load
+Прочитай `.claude/skills/explore/SKILL.md`
+
+## Prerequisites
+- [ ] `researches/<slug>/03_solution_strategy.md` существует
+- [ ] Promise `SOLUTION_DESIGNED` эмитирован
+- [ ] `{CHOSEN_CJM}` передан из Phase 2.5
+
+## Quality Gates
+- Определены 5 user scenarios
+- Задан think-aloud протокол
+- Указаны success/failure criteria
+
+## Promise Tag
+`<promise>USABILITY_PLAN_READY</promise>`
+```
+
+### 9.4. Протокол загрузки shard
+
+При старте каждой фазы командный файл явно загружает соответствующий shard:
+
+```markdown
+1. **Загрузи shard:** Прочитай `.claude/shards/phase-3-solve.shard.md`
+2. **Проверь prerequisites:** Убедись, что все условия shard выполнены
+3. **Загрузи скилл:** Прочитай скилл, указанный в shard
+```
+
+Это обеспечивает актуальность правил даже в очень длинных сессиях с большим контекстом.
+
+---
+
+## 10. Trust Tiers
+
+### 10.1. Система уровней доверия
+
+Trust Tier System -- это четырёхуровневая классификация скиллов по уровню проверенности и надёжности. Уровень доверия определяет, насколько можно полагаться на скилл в продуктивных исследованиях.
+
+| Tier | Метка | Требования | Признак надёжности |
+|------|-------|-----------|-------------------|
+| **Tier 3** | Verified | Eval test suites + детерминистическая валидация | Наивысший уровень, автоматическое тестирование |
+| **Tier 2** | Validated | Пройден `/bto-test` с Layer 2 score >= 7.0 | Проверен мульти-агентной панелью судей |
+| **Tier 1** | Structured | `SKILL.md` + `references/` или `modules/` | Структурирован, задокументирован |
+| **Tier 0** | Advisory | Только `SKILL.md` | Базовая документация, требует проверки |
+
+### 10.2. Текущие уровни скиллов
+
+| Скилл | Tier | Метка | Основание |
+|-------|------|-------|-----------|
+| explore | 1 | Structured | `SKILL.md` + `references/` |
+| frontend-design | 0 | Advisory | Только `SKILL.md`, нет references |
+| goap-research-ed25519 | 1 | Structured | `SKILL.md` + `references/` + `scripts/` |
+| problem-solver-enhanced | 1 | Structured | Расширенный `SKILL.md` с фреймворком TRIZ |
+| 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/` |
+| feature-adr | 1 | Structured | `SKILL.md` + `modules/` + `references/` |
+
+### 10.3. Применение уровней при загрузке скиллов
+
+| Tier | Поведение при загрузке |
+|------|----------------------|
+| Tier 0 | Предупреждение при использовании в продуктивном пайплайне: рекомендуется провести `/bto-test` |
+| Tier 1 | Стандартное использование; рекомендуется `/bto-test` для повышения |
+| Tier 2 | Полная уверенность; BTO-score указан в `SKILL.md` |
+| Tier 3 | Наивысшая уверенность; детерминистическая валидация доступна |
+
+### 10.4. Протокол повышения уровня
+
+Для повышения скилла с Tier 1 до Tier 2 или с Tier 2 до Tier 3:
+
+**Шаг 1.** Запустите оценку через BTO:
+
+```
+/bto-test .claude/skills/<name>/
+```
+
+**Шаг 2.** Проверьте результат Layer 2:
+
+- Layer 2 score >= 7.0 -- повышение до **Tier 2**
+- Layer 2 score >= 8.5 + существуют детерминистические eval tests -- повышение до **Tier 3**
+
+**Шаг 3.** Обновите `SKILL.md` скилла, добавив запись о повышении:
+
+```markdown
+---
+name: my-skill
+tier: 2
+bto_score: 7.8
+promoted_at: 2026-03-02
+---
+```
+
+**Шаг 4.** Обновите таблицу в разделе 10.2 данного руководства и в `CLAUDE.md`.
+
+### 10.5. Понижение уровня
+
+Если скилл был изменён после получения Tier 2/3, его уровень возвращается на Tier 1 (Structured) до повторного прохождения `/bto-test`. Это предотвращает ложное ощущение надёжности для изменённых, но не переоценённых скиллов.
+
+---
+
 ## Приложение A: Чеклист администратора
 
 ### При добавлении нового скилла
@@ -1149,7 +1317,19 @@ rm -rf researches/<slug>/
 │   ├── solve.md                ← /solve (Phase 3)
 │   ├── architecture-phase.md   ← /architecture-phase (Phase 4)
 │   ├── presentation.md         ← /presentation (Phase 5)
-│   └── harvest.md              ← /harvest
+│   ├── harvest.md              ← /harvest
+│   ├── brain-export.md         ← /brain-export
+│   ├── brain-import.md         ← /brain-import
+│   ├── init-platform.md        ← /init-platform
+│   ├── workers.md              ← /workers
+│   ├── dream.md                ← /dream
+│   ├── learning-stats.md       ← /learning-stats
+│   ├── verify-chain.md         ← /verify-chain
+│   ├── feature-adr.md          ← /feature-adr
+│   ├── bto.md                  ← /bto
+│   ├── bto-build.md            ← /bto-build
+│   ├── bto-test.md             ← /bto-test
+│   └── bto-optimize.md         ← /bto-optimize
 ├── rules/                      ← Правила (автоматические)
 │   ├── agent-swarm.md
 │   ├── anti-patterns.md
@@ -1157,14 +1337,35 @@ rm -rf researches/<slug>/
 │   ├── domain-specific.md
 │   ├── file-conventions.md
 │   ├── modular-reuse.md
-│   └── research-quality.md
+│   ├── research-quality.md
+│   ├── witness-chain.md
+│   ├── reward-learning.md
+│   ├── background-workers.md
+│   ├── dream-cycles.md
+│   ├── model-routing.md
+│   ├── trust-tiers.md
+│   ├── bto-quality-gates.md
+│   ├── feedback-loops.md
+│   └── feature-adr-conventions.md
+├── shards/                     ← Governance shards (per-phase rules)
+│   ├── phase-0-discovery.shard.md
+│   ├── phase-1-explore.shard.md
+│   ├── phase-2-research.shard.md
+│   ├── phase-25-cjm.shard.md
+│   ├── phase-3-solve.shard.md
+│   ├── phase-4-architecture.shard.md
+│   ├── phase-5-presentation.shard.md
+│   ├── bto-evaluation.shard.md
+│   └── feature-adr.shard.md
 ├── skills/                     ← Скиллы (загружаемые навыки)
 │   ├── explore/
 │   ├── frontend-design/
 │   ├── goap-research-ed25519/
 │   ├── presentation-storyteller/
 │   ├── problem-solver-enhanced/
-│   └── reverse-engineering-unicorn/
+│   ├── reverse-engineering-unicorn/
+│   ├── bto/
+│   └── feature-adr/
 └── agents/                     ← Шаблоны агентов
     └── (создаются по необходимости)
 ```

package/templates/docs/keysarium/03-user-guide.md

@@ -8,6 +8,19 @@
 
 1. [Быстрый старт (5 минут)](#1-быстрый-старт-5-минут)
 2. [Основные команды](#2-основные-команды)
+   - [2.1. /casarium](#21-casarium----полный-пайплайн)
+   - [2.2. /new-research](#22-new-research----создать-исследование)
+   - [2.3. /parallel-research](#23-parallel-research----несколько-кейсов)
+   - [2.4. Команды отдельных фаз](#24-команды-отдельных-фаз)
+   - [2.5. /harvest](#25-harvest----извлечение-знаний)
+   - [2.6. /brain-export и /brain-import](#26-brain-export-и-brain-import----портативные-знания)
+   - [2.7. /init-platform](#27-init-platform----мульти-платформенная-поддержка)
+   - [2.8. /workers](#28-workers----фоновые-воркеры)
+   - [2.9. /dream](#29-dream----dream-cycles)
+   - [2.10. /learning-stats](#210-learning-stats----аналитика-обучения)
+   - [2.11. /verify-chain](#211-verify-chain----верификация-цепочки)
+   - [2.12. /feature-adr](#212-feature-adr----адаптивная-разработка-фич)
+   - [2.13. /bto](#213-bto----build-test-optimize)
 3. [Работа с checkpoint-ами](#3-работа-с-checkpoint-ами)
 4. [Работа с CJM прототипом (Phase 2.5)](#4-работа-с-cjm-прототипом-phase-25)
 5. [Quick Mode (менее 2 часов)](#5-quick-mode-менее-2-часов)
@@ -198,6 +211,217 @@ researches/bank_kc_automation/
 
 Harvest находит универсальные паттерны, шаблоны и уроки, которые можно переиспользовать в будущих исследованиях.
 
+### 2.6. /brain-export и /brain-import -- портативные знания
+
+Экспорт и импорт накопленных знаний между проектами.
+
+```
+/brain-export [путь или "all"]   — Экспорт знаний в portable JSON
+/brain-import [файл.json]        — Импорт знаний из другого проекта
+```
+
+**Экспорт:**
+
+```
+/brain-export researches/bank_kc_automation/
+/brain-export all
+```
+
+Brain-контейнер включает: метаданные скиллов, паттерны по доменам, резюме исследований, паттерны из harvest, метрики пайплайна. Файл сохраняется в `.keysarium/exports/`.
+
+**Импорт:**
+
+```
+/brain-import .keysarium/exports/keysarium-brain-2026-03-01.json
+```
+
+Импорт использует стратегию merge-not-overwrite: существующие знания не перезаписываются, новые добавляются. Удобно для переноса накопленного опыта в новый проект или передачи коллеге.
+
+### 2.7. /init-platform -- мульти-платформенная поддержка
+
+Генерирует конфигурации для других AI-платформ, адаптируя скиллы и правила Keysarium к целевому формату.
+
+```
+/init-platform --platform cursor     — Cursor (.cursorrules)
+/init-platform --platform opencode   — OpenCode (.opencode/)
+/init-platform --platform copilot    — GitHub Copilot (.github/copilot-instructions.md)
+```
+
+**Пример:**
+
+```
+/init-platform --platform cursor
+```
+
+После выполнения в корне проекта появится файл `.cursorrules`, содержащий адаптированные инструкции для Cursor. Аналогично для других платформ.
+
+### 2.8. /workers -- фоновые воркеры
+
+Управление фоновыми воркерами для неблокирующих операций.
+
+```
+/workers start <type>   — Запуск воркера (consolidate, export-brain, health-check, dream-cycle)
+/workers status          — Статус активных воркеров
+/workers stop <id>       — Остановка воркера
+/workers list            — Список доступных типов
+```
+
+**Типы воркеров:**
+
+| Тип | Назначение | Модель |
+|-----|-----------|--------|
+| `consolidate` | Консолидация паттернов из завершённых исследований | sonnet |
+| `export-brain` | Фоновый экспорт brain в JSON | haiku |
+| `health-check` | Проверка здоровья системы | haiku |
+| `dream-cycle` | Анализ паттернов (concept graph + insights) | sonnet |
+
+**Пример запуска:**
+
+```
+/workers start consolidate
+/workers status
+/workers stop wkr-20260301-143022-consolidate
+```
+
+Воркеры работают в изоляции (`.keysarium/workers/`), не изменяют файлы в `researches/` и `features/`. Максимум 3 воркера одновременно.
+
+### 2.9. /dream -- Dream Cycles
+
+Анализ накопленных паттернов через несколько сессий.
+
+```
+/dream run       — Запуск dream cycle (concept graph + insights)
+/dream insights  — Показать последние инсайты
+/dream status    — Состояние триггеров
+/dream clear     — Очистить старые инсайты (оставить 10)
+```
+
+Dream cycle анализирует паттерны из истории исследований, например:
+- «Банковские кейсы требуют вдвое больше времени на Phase 2»
+- «TRIZ работает лучше Game Theory для ритейла»
+- «CJM Variant B выигрывает в 70% enterprise-кейсов»
+
+Инсайты автоматически применяются при запуске следующего `/casarium` -- система предложит учесть найденные паттерны. Запуск dream cycle предлагается системой в качестве рекомендации, когда накапливается достаточно данных (триггеры настраиваются).
+
+```
+/dream run
+/dream insights
+```
+
+Результаты хранятся в `.keysarium/insights/`. Максимум 10 файлов результатов.
+
+### 2.10. /learning-stats -- аналитика обучения
+
+```
+/learning-stats [--domain X] [--phase N]   — Reward learning статистика
+```
+
+Показывает статистику на основе reward-оценок (0.0--1.0), которые назначаются автоматически по ответам пользователя на checkpoint-ах:
+
+| Ответ на checkpoint | Reward | Метка |
+|--------------------|--------|-------|
+| `ок`, `next` (без правок) | 1.0 | excellent |
+| Правка 1 раздела | 0.7 | good |
+| Правки 3+ разделов | 0.3 | needs_work |
+| `начни заново` | 0.0 | failed |
+
+**Примеры:**
+
+```
+/learning-stats                   — Общая статистика по всем доменам и фазам
+/learning-stats --domain banking  — Статистика для банковского домена
+/learning-stats --phase 2         — Статистика для Phase 2 (Research)
+```
+
+Вывод включает: средние оценки по фазам, паттерны по доменам, эффективность скиллов. Помогает понять, какие фазы и домены требуют повышенного внимания.
+
+### 2.11. /verify-chain -- верификация цепочки
+
+```
+/verify-chain [путь к директории исследования]
+```
+
+Проверяет целостность SHA-256 цепочки свидетелей (witness chain) для артефактов исследования.
+
+**Пример:**
+
+```
+/verify-chain researches/bank_kc_automation/
+```
+
+Каждая фаза создаёт запись с хешем артефакта, связанную с предыдущей записью (hash chain). Это гарантирует, что артефакты не были изменены после создания. Цепочка хранится в `researches/<slug>/.witness-chain.json`.
+
+Особенно важно для банковского домена (требования ФЗ-152 к аудит-треилу). Рекомендуется запускать после завершения полного пайплайна как финальную проверку целостности.
+
+### 2.12. /feature-adr -- адаптивная разработка фич
+
+9-шаговый пайплайн для реализации программных фич с Complexity Router (S/M/L/XL).
+
+```
+/feature-adr [описание фичи]
+```
+
+**Пример:**
+
+```
+/feature-adr Добавить авторизацию через OAuth 2.0 с поддержкой Google и GitHub
+```
+
+**Шаги пайплайна:**
+
+| Шаг | Название | Назначение |
+|-----|---------|-----------|
+| 0 | Complexity Router | Определение уровня сложности (S/M/L/XL) |
+| 1 | Requirements | Структурированные требования |
+| 2 | Research | Исследование решений (только L/XL) |
+| 3 | ADR | Architecture Decision Record (только M+) |
+| 4 | DDD | Domain модель (только L/XL) |
+| 5 | Architecture | Архитектура (только M+) |
+| 6 | Implementation Plan | План реализации |
+| 7 | Code | Реализация кода |
+| 8 | QE | Проверка качества |
+
+**Уровни сложности:**
+
+| Tier | Scope | Активные шаги |
+|------|-------|--------------|
+| S | 1--3 файла | 0→1→6→7→8 |
+| M | 4--10 файлов | 0→1→3→5→6→7→8 |
+| L | 11--30 файлов | Полный пайплайн |
+| XL | 30+ файлов | Полный DAG + multi-agent |
+
+Артефакты сохраняются в `features/<feature-slug>/` (не в `researches/`). Уровень сложности определяется автоматически на шаге 0, но может быть скорректирован вами на первом checkpoint-е.
+
+### 2.13. /bto -- Build-Test-Optimize
+
+Система мульти-агентной оценки и оптимизации скиллов и команд.
+
+```
+/bto [путь]            — Полный цикл: BUILD → TEST → OPTIMIZE
+/bto-build [описание]  — Генерация нового скилла/команды
+/bto-test [путь]       — Мульти-агентная оценка (Layer 0→1→2)
+/bto-optimize [путь]   — Эволюционная оптимизация за 3 раунда
+```
+
+**Примеры:**
+
+```
+/bto-test .claude/skills/explore/
+/bto-optimize .claude/skills/problem-solver-enhanced/
+/bto-build Новый скилл для анализа конкурентов в телекоме
+```
+
+**Архитектура оценки (TEST):**
+
+| Layer | Роль | Модель | Назначение |
+|-------|------|--------|-----------|
+| Layer 0 | Структурные проверки | haiku | 71 детерминистическая проверка: структура, плейсхолдеры, кодировка |
+| Layer 1 | Семантическая базовая оценка | haiku | Быстрая проверка связности и релевантности |
+| Layer 2 | Полная панель 3 судей | sonnet | Domain Expert + Critic + Completeness Auditor |
+| Meta | Разрешение разногласий | sonnet | Срабатывает, если разброс оценок > 3 пункта |
+
+Результат Layer 2: взвешенная оценка 0--10 (Domain Expert 40% / Critic 30% / Auditor 30%). Оценка ≥ 7.0 переводит скилл в Tier 2 (Validated), ≥ 8.5 при наличии тест-суитов -- в Tier 3 (Verified).
+
 ---
 
 ## 3. Работа с checkpoint-ами