@dzhechkov/keysarium 1.1.2 → 1.2.0

package/templates/docs/keysarium/05-architecture.md

@@ -10,6 +10,13 @@
 6. [Agent Swarm Architecture](#agent-swarm-architecture)
 7. [Модульность для переиспользования](#модульность-для-переиспользования)
 8. [Сравнение с claude.ai](#сравнение-с-claudeai)
+9. [Governance System](#governance-system)
+10. [Memory & Learning System](#memory--learning-system)
+11. [Verification System](#verification-system)
+12. [Trust Tier System](#trust-tier-system)
+13. [Background Workers](#background-workers)
+14. [Multi-Platform Support](#multi-platform-support)
+15. [keysarium-core Package](#keysarium-core-package)
 
 ---
 
@@ -704,3 +711,177 @@ Product Keysarium 2026 спроектирован для работы в Claude
 | Командная работа с git | Claude Code |
 | Прототипирование скилла | claude.ai (быстрый feedback loop) |
 | Production pipeline | Claude Code (воспроизводимость) |
+
+---
+
+## Governance System
+
+### Constitution & Shards
+
+Каждая фаза загружает свой governance shard из `.claude/shards/`:
+
+```
+.claude/shards/
+├── 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
+```
+
+Shard содержит: time budget, skill to load, prerequisites, quality gates, promise tag. Решает проблему context drift при длинных сессиях.
+
+### Semantic Completion Promises
+
+Каждый checkpoint включает машинно-читаемый `<promise>` тег:
+
+| Фаза | Promise Tag |
+|------|------------|
+| Phase 0 | `DISCOVERY_COMPLETE` |
+| Phase 1 | `CASE_EXPLORED` |
+| Phase 2 | `RESEARCH_PARANOID_PASSED` |
+| Phase 2.5 | `CJM_VALIDATED` |
+| Phase 3 | `SOLUTION_DESIGNED` |
+| Phase 4 | `ARCHITECTURE_DEFINED` |
+| Phase 5 | `PRESENTATION_READY` |
+
+---
+
+## Memory & Learning System
+
+### Reward-calibrated Learning
+
+Персистентная память в `.keysarium/memory/`:
+
+1. **Pre-phase:** `memory_query()` загружает релевантные паттерны из прошлых кейсов
+2. **Post-checkpoint:** `memory_store()` сохраняет результат с reward score (0.0-1.0)
+
+Reward mapping: "ок" → 1.0, minor adjustments → 0.7, significant rework → 0.3, full restart → 0.0
+
+### Cross-phase Feedback Loops
+
+6 именованных loops формализуют передачу данных:
+
+| Loop | Direction | Key Variable |
+|------|-----------|-------------|
+| CJM → Solve | Phase 2.5 → 3 | `{CHOSEN_CJM}` |
+| Research → Presentation | Phase 2 → 5 | Verified sources |
+| Discovery → All | Phase 0 → 1-5 | `{DOMAIN}`, `{PRIMARY_USER}` |
+| Solve → Architecture | Phase 3 → 4 | `{SOLUTION_CONCEPT}` |
+| BTO Judges → Optimizer | Layer 2 → Optimize | `{WEAK_DIMENSIONS}` |
+| History → Discovery | Past → Phase 0 | Domain patterns |
+
+### Dream Cycles
+
+Background pattern analysis engine:
+
+```mermaid
+graph LR
+    A[Pattern Collection] --> B[Trigger Check]
+    B -->|Volume >= 20| C[DreamEngine]
+    B -->|Time >= 60 min| C
+    B -->|Quality gate fail| C
+    C --> D[Concept Graph]
+    D --> E[Insight Generation]
+    E --> F[Applied at next pipeline start]
+```
+
+Инсайты хранятся в `.keysarium/insights/` (max 10 файлов, chronological retention).
+
+---
+
+## Verification System
+
+### SHA-256 Witness Chain
+
+Каждый phase artifact получает hash, chain связывает артефакты:
+
+```
+Phase 0: hash_0 = SHA-256(00_product_discovery.md)
+Phase 1: hash_1 = SHA-256(01_case_brief.md + hash_0)
+Phase 2: hash_2 = SHA-256(02_research_findings.md + hash_1)
+...
+```
+
+Хранится в `researches/<slug>/.witness-chain.json`. Невозможно подменить промежуточный артефакт без разрыва цепочки.
+
+### BTO Judge Attestation
+
+Криптографическое доказательство независимости судей в `.judge-attestations.json`:
+- Каждый judge записывает оценку с SHA-256 hash ДО того, как видит оценки других
+- Timestamps доказуемо верифицируют изоляцию judges
+
+---
+
+## Trust Tier System
+
+| Tier | Label | Requirements |
+|------|-------|-------------|
+| 3 | Verified | Eval test suites + deterministic validation |
+| 2 | Validated | /bto-test Layer 2 score >= 7.0 |
+| 1 | Structured | SKILL.md + references/ or modules/ |
+| 0 | Advisory | Only SKILL.md |
+
+Повышение: `/bto-test .claude/skills/<name>/` → score >= 7.0 → Tier 2 → score >= 8.5 + eval tests → Tier 3.
+
+---
+
+## Background Workers
+
+```mermaid
+graph TB
+    CMD["/workers start consolidate"] --> REG[Registry<br/>.keysarium/workers/registry.json]
+    REG --> W1[Worker: consolidate<br/>model=sonnet]
+    REG --> W2[Worker: health-check<br/>model=haiku]
+    REG --> W3[Worker: dream-cycle<br/>model=sonnet]
+    W1 --> OUT1[.keysarium/workers/{id}/]
+    W2 --> OUT2[.keysarium/workers/{id}/]
+    W3 --> OUT3[.keysarium/workers/{id}/]
+```
+
+Max 3 concurrent, strict isolation (write only to .keysarium/workers/), never opus.
+
+---
+
+## Multi-Platform Support
+
+```mermaid
+graph LR
+    CORE[Keysarium Skills + Rules] --> CC[Claude Code<br/>.claude/]
+    CORE --> CUR[Cursor<br/>.cursorrules]
+    CORE --> OC[OpenCode<br/>.opencode/]
+    CORE --> COP[GitHub Copilot<br/>.github/copilot-instructions.md]
+```
+
+`/init-platform --platform <name>` генерирует platform-specific конфигурации. Skills и rules -- тот же markdown, меняется только формат загрузки.
+
+---
+
+## keysarium-core Package
+
+3-package architecture:
+
+```
+@dzhechkov/keysarium-core          ← Domain-agnostic framework
+        ↑                ↑
+   peerDep          peerDep
+        |                |
+@dzhechkov/keysarium    @dzhechkov/skills-bto
+```
+
+Core modules (22 files):
+
+| Module | Files | Purpose |
+|--------|-------|---------|
+| governance/ | 3 | Constitution, shard protocol, checkpoint protocol |
+| memory/ | 3 | Memory protocol, reward tracker, dream engine |
+| orchestration/ | 4 | Queen protocol, topologies, workers, model routing |
+| verification/ | 3 | Witness chain, judge attestation, audit trail |
+| trust-tiers/ | 2 | Tier system, promotion protocol |
+| platform/ | 4 | Adapter registry + templates |
+
+All protocols are domain-agnostic -- any team can build custom multi-agent pipelines.

package/templates/docs/keysarium/06-user-flows.md

@@ -13,6 +13,11 @@
 9. [Admin Flow: Расширение пайплайна новой фазой](#admin-flow-расширение-пайплайна-новой-фазой)
 10. [Admin Flow: Массовый harvest](#admin-flow-массовый-harvest)
 11. [Error Flows](#error-flows)
+12. [User Flow: BTO — Build-Test-Optimize](#user-flow-bto--build-test-optimize)
+13. [User Flow: Feature ADR](#user-flow-feature-adr)
+14. [User Flow: Background Workers](#user-flow-background-workers)
+15. [User Flow: Dream Cycles](#user-flow-dream-cycles)
+16. [User Flow: Brain Export/Import](#user-flow-brain-exportimport)
 
 ---
 
@@ -923,3 +928,233 @@ flowchart TD
 | Anti-pattern обнаружен | Нет (предупреждение) | Флаг + автоматическое исправление |
 | "Just add GPT" в решении | Нет (предупреждение) | Запросить конкретные модели + pipeline |
 | Непроверенное утверждение | Нет (маркировка) | `[UNVERIFIED]` + флаг |
+
+---
+
+## User Flow: BTO — Build-Test-Optimize
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    actor U as User
+    participant C as Claude (/bto)
+    participant FS as File System
+    participant J1 as Judge 1 (Expert)
+    participant J2 as Judge 2 (Critic)
+    participant J3 as Judge 3 (Auditor)
+
+    U->>C: /bto .claude/skills/my-skill/
+
+    Note over C: ═══ BUILD ═══
+    C->>FS: Read SKILL.md
+    C->>C: Генерация/улучшение артефакта
+    C->>FS: Write улучшенный SKILL.md
+    C-->>U: BUILD complete
+
+    Note over C: ═══ TEST (Layer 0) ═══
+    C->>C: 71 deterministic checks (haiku)
+    alt Layer 0 PASS
+        Note over C: ═══ TEST (Layer 1) ═══
+        C->>C: Semantic baseline (haiku)
+    else Layer 0 FAIL
+        C->>C: Auto-retry (до 3 раз)
+    end
+
+    Note over C: ═══ TEST (Layer 2) ═══
+    par 3 judges parallel (sonnet)
+        C->>J1: Domain Expert evaluation
+        C->>J2: Critic evaluation
+        C->>J3: Completeness Auditor
+    end
+    J1-->>C: Score + rationale
+    J2-->>C: Score + rationale
+    J3-->>C: Score + rationale
+    C->>C: Weighted average (0.4 / 0.3 / 0.3)
+    C-->>U: TEST score: X.X/10
+
+    Note over C: ═══ OPTIMIZE ═══
+    loop 3 rounds
+        C->>C: Mutation + evaluation
+        C->>C: Check delta > 0.5
+    end
+    C-->>U: OPTIMIZE complete, final score: Y.Y/10
+```
+
+### Step by Step
+
+**Шаг 1.** Запуск BTO:
+```
+/bto .claude/skills/my-skill/
+```
+
+**Шаг 2.** BUILD — генерация или улучшение артефакта.
+
+**Шаг 3.** TEST — 3-уровневая оценка:
+- Layer 0: структурные проверки (haiku)
+- Layer 1: семантический базовый уровень (haiku)
+- Layer 2: панель из 3 судей (sonnet), работают изолированно
+
+**Шаг 4.** OPTIMIZE — эволюционная оптимизация за 3 раунда. Останавливается при delta ≤ 0.5 три раза подряд.
+
+---
+
+## User Flow: Feature ADR
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    actor U as User
+    participant C as Claude (/feature-adr)
+    participant FS as File System
+
+    U->>C: /feature-adr Add user authentication
+
+    Note over C: Step 0: Complexity Router (haiku)
+    C->>C: Classify: S / M / L / XL
+    C-->>U: Checkpoint 0: Tier = M (4-10 files)
+    U->>C: "ок"
+
+    Note over C: Step 1: Requirements (sonnet)
+    C->>FS: Write features/add-user-auth/01_requirements.md
+    C-->>U: Checkpoint 1
+    U->>C: "ок"
+
+    Note over C: Step 3: ADR (opus) [M tier — skip Step 2]
+    C->>FS: Write features/add-user-auth/03_adr/001-auth-strategy.md
+    C-->>U: Checkpoint 3
+    U->>C: "ок"
+
+    Note over C: Step 5: Architecture (opus)
+    C->>FS: Write features/add-user-auth/05_architecture.md
+    C-->>U: Checkpoint 5
+    U->>C: "ок"
+
+    Note over C: Step 6: Implementation Plan (sonnet)
+    C->>FS: Write features/add-user-auth/06_implementation_plan.md
+
+    Note over C: Step 7: Code (opus)
+    C->>C: Implement code changes in codebase
+    C->>FS: Write features/add-user-auth/07_code_changes/change_manifest.md
+
+    Note over C: Step 8: QE (sonnet)
+    C->>FS: Write features/add-user-auth/08_qe_report.md
+    C-->>U: Feature complete!
+```
+
+### Complexity Tiers
+
+| Tier | Scope | Шаги |
+|------|-------|------|
+| **S** | 1-3 файла, 1 домен | 0→1→6→7→8 |
+| **M** | 4-10 файлов, 1-2 домена | 0→1→3→5→6→7→8 |
+| **L** | 11-30 файлов, 2-4 домена | Полный pipeline |
+| **XL** | 30+ файлов, cross-cutting | Full DAG + multi-agent |
+
+---
+
+## User Flow: Background Workers
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    actor U as User
+    participant C as Claude (/workers)
+    participant FS as File System
+    participant W as Background Worker
+
+    U->>C: /workers start consolidate
+    C->>FS: Check registry (max 3 workers)
+    C->>FS: Create .keysarium/workers/{id}/
+    C->>W: Spawn agent (model=sonnet)
+    W->>FS: Read researches/*
+    W->>W: Pattern consolidation
+    W->>FS: Write .keysarium/workers/{id}/output.json
+    W->>FS: Update status.json
+    C-->>U: Worker started: wkr-20260301-143022-consolidate
+
+    U->>C: /workers status
+    C->>FS: Read registry.json + status files
+    C-->>U: 1 active, 0 completed, 2 slots available
+
+    U->>C: /workers stop wkr-20260301-143022-consolidate
+    C->>FS: Update registry
+    C-->>U: Worker stopped
+```
+
+### Типы воркеров
+
+| Тип | Модель | Назначение |
+|-----|--------|-----------|
+| `consolidate` | sonnet | Консолидация паттернов из исследований |
+| `health-check` | haiku | Проверка здоровья системы |
+| `export-brain` | haiku | Фоновый экспорт знаний |
+| `dream-cycle` | sonnet | Dream cycle (concept graph + insights) |
+
+---
+
+## User Flow: Dream Cycles
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    actor U as User
+    participant C as Claude (/dream)
+    participant FS as File System
+
+    U->>C: /dream run
+    C->>FS: Read .keysarium/memory/**
+    C->>C: Build concept graph
+    C->>C: Cross-domain pattern analysis
+    C->>C: Generate insights (4 types)
+    C->>FS: Write .keysarium/insights/dream-20260301-143022.json
+    C->>FS: Update trigger-state.json (reset counters)
+    C-->>U: Dream complete: 5 insights generated
+
+    U->>C: /dream insights
+    C->>FS: Read .keysarium/insights/dream-*.json
+    C-->>U: Insights list (sorted by recency)
+
+    U->>C: /dream status
+    C->>FS: Read trigger-state.json
+    C-->>U: Records since last dream: 15/20, Time: 45/60 min
+```
+
+### Типы инсайтов
+
+| Тип | Пример |
+|-----|--------|
+| Performance | "Phase 2 takes 2x longer for banking domain" |
+| Effectiveness | "TRIZ produces higher scores than Game Theory for retail" |
+| Preference | "CJM Variant B selected in 70% of enterprise cases" |
+| Anti-pattern | "Phase 5 consistently gets rework when HITL skipped in Phase 3" |
+
+---
+
+## User Flow: Brain Export/Import
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    actor U as User
+    participant C as Claude
+    participant FS as File System
+
+    Note over U,C: === EXPORT ===
+    U->>C: /brain-export all
+    C->>FS: Read researches/*, .keysarium/memory/*, TOOLKIT_HARVEST.md
+    C->>C: Assemble: skills + patterns + research summaries + metrics
+    C->>FS: Write keysarium-brain.json
+    C-->>U: Brain exported: 15 patterns, 3 domain profiles
+
+    Note over U,C: === IMPORT (другой проект) ===
+    U->>C: /brain-import keysarium-brain.json
+    C->>FS: Read keysarium-brain.json
+    C->>C: Selective merge (merge-not-overwrite)
+    C->>FS: Merge into .keysarium/memory/
+    C-->>U: Imported: 12 patterns merged, 3 skipped (duplicates)
+```