@dzhechkov/keysarium 1.1.2 → 1.3.0

package/templates/.claude/rules/reward-learning.md

@@ -0,0 +1,124 @@
+# Reward Learning Rules
+
+## Purpose
+
+Govern how the Keysarium pipeline integrates with the Reward-Calibrated Learning System. These rules define when and how to call `memory_query()` and `memory_store()`, how reward scores are assigned, and how historical patterns influence phase execution.
+
+## Core Protocol
+
+Read `lib/memory-protocol.md` for the full protocol specification.
+Read `lib/reward-tracker.md` for analytics and pattern detection.
+
+## When to Call memory_query()
+
+**Trigger:** At the START of every pipeline phase (Phase 0 through Phase 5).
+
+**Protocol:**
+1. Before loading the phase's governance shard, check if `.keysarium/memory/` exists.
+2. If it exists, call `memory_query()` with the current context:
+   - `phase`: Current phase identifier (e.g., "phase-2")
+   - `domain`: Detected domain from Phase 0 (or "unknown" if Phase 0 has not run yet)
+   - `slug`: Current case slug
+   - `skill`: Skill about to be loaded for this phase
+3. Log the number of patterns loaded.
+4. If relevant patterns are found, incorporate the top 3 into the phase brief:
+   - Include high-reward approaches from similar past cases
+   - Apply actionable advice from domain patterns
+   - Note any bottleneck warnings for the current phase/domain combination
+5. If no patterns are found (first run or no relevant data), proceed normally.
+
+**Exception:** Phase 0 (Discovery) may not have a domain yet. Query with `domain: "unknown"` to load cross-domain patterns.
+
+## When to Call memory_store()
+
+**Trigger:** At every CHECKPOINT, after the user responds.
+
+**Protocol:**
+1. After displaying the checkpoint banner and receiving user response.
+2. Classify the user response into a reward level (see Reward Assignment below).
+3. Call `memory_store()` with:
+   - The phase result (artifacts created, promise tag emitted)
+   - The reward score and label
+   - Context metadata (upstream promises, patterns loaded, agent count)
+   - Outcome metadata (user response, iteration count)
+4. Log the stored reward.
+5. Continue with the checkpoint protocol as normal (proceed / adjust / redo).
+
+**Exception:** If the session ends without a user response at the checkpoint, do NOT store a record. Only explicit user responses generate reward data.
+
+## Reward Assignment
+
+Map the user's checkpoint response to a reward score:
+
+| User Response Pattern | Reward | Label | Examples |
+|----------------------|--------|-------|----------|
+| Immediate approval | 1.0 | excellent | "ok", "ок", "next", "продолжай", "good", single-word approval |
+| Minor adjustments | 0.7 | good | "углуби X", "expand section Y", "add one more competitor", feedback on 1 area |
+| Significant rework | 0.3 | needs_work | "rework the approach", "this misses the point of X and Y", feedback on 3+ areas |
+| Complete restart | 0.0 | failed | "start over", "this is wrong", "redo this phase completely" |
+
+### Classification Rules
+
+1. **Count the areas of feedback:** 0 areas = 1.0, 1 area = 0.7, 2+ areas = 0.3, full restart = 0.0
+2. **Positive feedback with minor note** counts as 1.0 (e.g., "great work, just fix the typo")
+3. **Multiple rounds:** If user gives feedback more than twice on the same phase, cap reward at 0.3
+4. **Ambiguous responses:** Default to 0.7 (assume minor adjustment)
+
+## Integration with Promise Tags
+
+Every `memory_store()` call includes the promise tag emitted at the checkpoint:
+
+| Phase | Promise Tag in Record |
+|-------|----------------------|
+| 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` |
+
+If a promise is `_INCOMPLETE`, the reward should be 0.3 or lower.
+
+## Integration with Feedback Loops
+
+This system adds a new feedback loop to the Variable Registry (see `.claude/rules/feedback-loops.md`):
+
+### Loop 7: Memory -> All Phases
+
+| Property | Value |
+|----------|-------|
+| Direction | `.keysarium/memory/` -> Phase 0-5 start |
+| Variable | `{MEMORY_PATTERNS}` |
+| Payload | Top reward records + domain patterns from memory_query() |
+| Consumers | All phases (loaded at phase start) |
+| Persistence | `.keysarium/memory/{domain}/{slug}/` |
+
+**Contract:** `memory_query()` is called before each phase starts. Empty result is acceptable (first run).
+
+## Retention Policy
+
+- **Default:** 90 days from record creation
+- **Configuration:** Set in `.keysarium/memory/config.json` via `retention_days`
+- **Enforcement:** Expired records are purged during `memory_query()` calls
+- **Override:** Set `retention_days: 0` to disable expiration (keep forever)
+- **Manual purge:** Delete `.keysarium/memory/` directory to reset all memory
+
+## Error Handling
+
+| Situation | Behavior |
+|-----------|----------|
+| `.keysarium/memory/` does not exist | `memory_query()` returns empty; `memory_store()` creates it |
+| `config.json` missing | Use defaults (90 days, 10 max results, enabled) |
+| Corrupted JSON file during query | Skip file, log warning, continue with other records |
+| Write failure during store | Log error, continue pipeline (memory is non-blocking) |
+| Unknown domain | Store under `unknown/` directory |
+
+## Rules Summary
+
+1. **ALWAYS** call `memory_query()` at the start of every phase
+2. **ALWAYS** call `memory_store()` at every checkpoint after user responds
+3. **NEVER** block the pipeline if memory operations fail
+4. **NEVER** store a record without an explicit user response
+5. **ALWAYS** log memory operations (patterns loaded, reward stored)
+6. Memory operations are **advisory** -- they enhance quality but are not mandatory gates

package/templates/.claude/shards/feature-adr.shard.md

@@ -0,0 +1,98 @@
+# Feature ADR — Governance Shard
+
+## Skill
+Load: `.claude/skills/feature-adr/SKILL.md`
+
+## Prerequisites
+- None (standalone command, not part of casarium pipeline)
+
+## Mandatory Outputs by Tier
+
+### Tier S
+- `features/<slug>/00_complexity_assessment.md`
+- `features/<slug>/06_implementation_plan.md` (or inline)
+- `features/<slug>/08_qe_report.md`
+- `features/<slug>/README.md`
+- Actual code changes in repository
+
+### Tier M
+All of S, plus:
+- `features/<slug>/01_requirements.md`
+- `features/<slug>/03_adr/001-*.md`
+- `features/<slug>/05_architecture.md`
+- `features/<slug>/07_code_changes/change_manifest.md`
+- `features/<slug>/diagrams/` (component diagram)
+
+### Tier L
+All of M, plus:
+- `features/<slug>/02_research.md`
+- `features/<slug>/04_domain_model.md`
+- `features/<slug>/diagrams/domain-model.mermaid`
+- `features/<slug>/diagrams/architecture-c4.mermaid`
+- `features/<slug>/diagrams/sequence-*.mermaid`
+
+### Tier XL
+All of L (full depth on every artifact)
+
+## Step-Level Quality Gates
+
+| Step | Gate |
+|------|------|
+| 0 | Tier classification justified with dimension scores |
+| 1 | All requirements have acceptance criteria (M+) |
+| 2 | Research findings verified, not hallucinated (L/XL) |
+| 3 | Every ADR has ≥2 alternatives (M+) |
+| 4 | Domain model compatible with existing codebase (L/XL) |
+| 5 | Mermaid diagrams valid syntax (M+) |
+| 6 | Task dependencies form valid DAG |
+| 7 | Code follows existing codebase conventions |
+| 8 | No blocker findings remain, all MUST requirements pass |
+
+## Agent Swarm
+
+### S/M tier
+Sequential execution. No parallel agents needed.
+
+### L tier
+- Steps 2+3: 2 parallel agents (sonnet + opus)
+- Step 8: 3 parallel agents (sonnet × 3)
+
+### XL tier
+- Steps 2+3: 2 parallel agents
+- Steps 4+5: 2 parallel agents (if Step 3 done)
+- Step 7: N parallel agents (per module)
+- Step 8: 3 parallel agents (review panel)
+
+## Model Routing
+
+| Step | Model | Rationale |
+|------|-------|-----------|
+| 0 | haiku | Simple classification |
+| 1 | sonnet | Analytical requirements |
+| 2 | sonnet | Research synthesis |
+| 3 | opus | Complex trade-off reasoning |
+| 4 | opus | Domain modeling |
+| 5 | opus | System design |
+| 6 | sonnet | Task decomposition |
+| 7 | opus | Code generation |
+| 8 | sonnet | Review and testing |
+
+## Promise Tags
+
+| Step | Promise |
+|------|---------|
+| 0 | `<promise>FEATURE_ADR_ROUTED</promise>` |
+| 1 | `<promise>FEATURE_ADR_REQUIREMENTS_GATHERED</promise>` |
+| 2-5 | `<promise>FEATURE_ADR_DESIGNED</promise>` |
+| 6 | `<promise>FEATURE_ADR_PLANNED</promise>` |
+| 7 | `<promise>FEATURE_ADR_IMPLEMENTED</promise>` |
+| 8 | `<promise>FEATURE_ADR_VERIFIED</promise>` |
+
+## Anti-Patterns to Check
+
+- Skip Step 0 → BLOCK
+- Code without plan (skip Step 6) → BLOCK
+- No QE (skip Step 8) → BLOCK
+- Over-engineer S-tier (run full pipeline for trivial change) → FLAG
+- Under-engineer XL-tier (skip ADR/DDD) → FLAG
+- ADR with only 1 alternative → FLAG

package/templates/.claude/skills/feature-adr/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: feature-adr
+description: >
+  9-step feature development pipeline with Complexity Router (S/M/L/XL),
+  ADR-driven architecture decisions, DDD modeling, and multi-agent QE.
+  Triggers on "реализуй фичу", "feature implementation", "добавь функциональность",
+  "implement feature", "/feature-adr".
+trust_tier: 0
+trust_tier_label: "Advisory"
+trust_tier_path: "Run /bto-test to promote to Tier 1"
+---
+
+# Feature ADR — Adaptive Feature Development Pipeline
+
+> 9-шаговый pipeline для разработки фич любой сложности.
+> Complexity Router автоматически определяет масштаб (S/M/L/XL) и пропускает ненужные шаги.
+
+## When To Activate
+
+Trigger on:
+- "реализуй фичу [описание]"
+- "implement feature [description]"
+- "добавь функциональность [описание]"
+- "feature [описание]"
+- `/feature-adr [описание или путь к issue]`
+
+## Architecture
+
+```
+.claude/skills/feature-adr/
+├── SKILL.md                           ← This file (orchestrator)
+├── modules/
+│   ├── 00-complexity-router.md        ← Step 0: S/M/L/XL classification
+│   ├── 01-requirements.md             ← Step 1: Requirements gathering
+│   ├── 02-research.md                 ← Step 2: Analogues & patterns research
+│   ├── 03-adr.md                      ← Step 3: Architecture Decision Records
+│   ├── 04-ddd.md                      ← Step 4: Domain-Driven Design
+│   ├── 05-architecture.md             ← Step 5: Technical architecture
+│   ├── 06-implementation-plan.md      ← Step 6: Task decomposition & ordering
+│   ├── 07-code.md                     ← Step 7: Code generation
+│   └── 08-qe.md                       ← Step 8: Quality Engineering
+├── references/
+│   ├── complexity-matrix.md           ← S/M/L/XL criteria & step activation
+│   ├── adr-template.md                ← ADR document template
+│   ├── c4-template.md                 ← C4 diagram templates
+│   └── qe-checklist.md                ← Quality engineering checklist
+└── examples/
+    └── sample-feature-output.md       ← Example output for M-tier feature
+```
+
+## Pipeline Overview
+
+```
+Step 0        Step 1          Step 2        Step 3       Step 4
+ROUTER   →  REQUIREMENTS  →  RESEARCH  →   ADR    →    DDD
+ (all)        (all)          (L/XL)       (M+)        (L/XL)
+                                            │            │
+                                            └──→ Step 5 ←┘
+                                            ARCHITECTURE
+                                              (M+)
+                                                │
+                                                ↓
+                                           Step 6
+                                         IMPL PLAN
+                                           (all)
+                                              │
+                                              ↓
+                                           Step 7
+                                            CODE
+                                           (all)
+                                              │
+                                              ↓
+                                           Step 8
+                                             QE
+                                           (all)
+```
+
+## Complexity Tiers
+
+| Tier | Scope | Steps | Example |
+|------|-------|-------|---------|
+| **S** | 1-3 files, single domain | 0→1→6→7→8 | Bug fix, config change, small util |
+| **M** | 4-10 files, 1-2 domains | 0→1→3→5(light)→6→7→8 | New API endpoint, UI component |
+| **L** | 11-30 files, 2-4 domains | 0→1→2→3→4→5→6→7→8 | New module, integration |
+| **XL** | 30+ files, cross-cutting | Full DAG with parallelism | New subsystem, major refactor |
+
+See `references/complexity-matrix.md` for detailed classification criteria.
+
+## Step Activation Matrix
+
+```
+Step                    | S | M | L | XL | Model   |
+───────────────────────────────────────────────────────
+0 Complexity Router     | ✓ | ✓ | ✓ | ✓  | haiku   |
+1 Requirements          | ✓ | ✓ | ✓ | ✓  | sonnet  |
+2 Research              | - | - | ✓ | ✓  | sonnet  |
+3 ADR                   | - | ✓ | ✓ | ✓  | opus    |
+4 DDD                   | - | - | ✓ | ✓  | opus    |
+5 Architecture          | - | ✓ | ✓ | ✓  | opus    |
+6 Implementation Plan   | ✓ | ✓ | ✓ | ✓  | sonnet  |
+7 Code                  | ✓ | ✓ | ✓ | ✓  | opus    |
+8 QE                    | ✓ | ✓ | ✓ | ✓  | sonnet  |
+```
+
+## DAG Dependencies
+
+Steps are NOT purely linear. The DAG defines what can run in parallel:
+
+```
+Group 1 (sequential): Step 0 → Step 1
+Group 2 (parallel):   Step 2 ‖ Step 3  (after Step 1)
+Group 3 (parallel):   Step 4 ‖ Step 5  (after Steps 2+3)
+Group 4 (sequential): Step 6 (after Step 5)
+Group 5 (sequential): Step 7 (after Step 6)
+Group 6 (sequential): Step 8 (after Step 7)
+```
+
+For tiers S/M, the DAG collapses to a linear sequence (no parallelism needed).
+
+## Agent Swarm Strategy
+
+### Per-Step Parallelism (L/XL tiers only)
+
+| Step | Agents | Tasks |
+|------|--------|-------|
+| Step 2 | 2 parallel (sonnet) | Codebase patterns ‖ External analogues |
+| Step 3+4 | 2 parallel (opus) | ADR drafting ‖ DDD modeling |
+| Step 7 | N parallel (opus) | One agent per independent module/file |
+| Step 8 | 3 parallel (sonnet) | Unit tests ‖ Integration tests ‖ Code review |
+
+### Cross-Step Parallelism
+
+For L/XL: Steps 2 and 3 run in parallel after Step 1 completes.
+For L/XL: Steps 4 and 5 can overlap if Step 3 finishes before Step 2.
+
+## Execution Protocol
+
+### 1. Load Governance
+```
+Read: .claude/shards/feature-adr.shard.md
+```
+
+### 2. Run Step 0 (Complexity Router)
+```
+Read: modules/00-complexity-router.md
+Read: references/complexity-matrix.md
+→ Output: {COMPLEXITY_TIER}, {ACTIVE_STEPS}, {TIME_BUDGET}
+→ Checkpoint 0
+```
+
+### 3. Execute Active Steps per DAG
+For each active step:
+```
+Read: modules/<step>.md
+Execute protocol
+→ Create artifacts in features/<feature-slug>/
+→ Checkpoint N
+```
+
+### 4. Final Verification
+After Step 8 completes, verify:
+- All mandatory artifacts exist per tier
+- QE checks passed
+- ADR decisions are traceable to code (L/XL)
+
+## Cross-Phase Variables
+
+| Variable | Set In | Used In | Type |
+|----------|--------|---------|------|
+| `{COMPLEXITY_TIER}` | Step 0 | All steps | S/M/L/XL |
+| `{ACTIVE_STEPS}` | Step 0 | Orchestrator | list[int] |
+| `{TIME_BUDGET}` | Step 0 | All steps | dict |
+| `{REQUIREMENTS}` | Step 1 | Steps 2-8 | structured |
+| `{RESEARCH_FINDINGS}` | Step 2 | Steps 3-5 | structured |
+| `{ADR_DECISIONS}` | Step 3 | Steps 4-7 | list[ADR] |
+| `{DOMAIN_MODEL}` | Step 4 | Steps 5-7 | structured |
+| `{ARCHITECTURE}` | Step 5 | Steps 6-7 | structured |
+| `{IMPL_PLAN}` | Step 6 | Step 7 | list[task] |
+| `{QE_RESULTS}` | Step 8 | Final report | structured |
+
+## Output Directory Structure
+
+All artifacts are created in `features/<feature-slug>/`:
+
+```
+features/<feature-slug>/
+├── 00_complexity_assessment.md        ← Always
+├── 01_requirements.md                 ← Always
+├── 02_research.md                     ← L/XL only
+├── 03_adr/                            ← M+ only
+│   ├── 001-<decision>.md
+│   └── ...
+├── 04_domain_model.md                 ← L/XL only
+├── 05_architecture.md                 ← M+ only
+├── 06_implementation_plan.md          ← Always
+├── 07_code_changes/                   ← Always (actual code in repo)
+│   └── change_manifest.md             ← List of modified files
+├── 08_qe_report.md                    ← Always
+├── diagrams/                          ← M+ only
+│   ├── architecture-c4.mermaid
+│   ├── sequence-*.mermaid
+│   └── domain-model.mermaid
+└── README.md                          ← Always (auto-generated summary)
+```
+
+## Promise Tags
+
+| Step | Promise Tag |
+|------|-------------|
+| Step 0 | `<promise>FEATURE_ADR_ROUTED</promise>` |
+| Step 1 | `<promise>FEATURE_ADR_REQUIREMENTS_GATHERED</promise>` |
+| Steps 2-5 | `<promise>FEATURE_ADR_DESIGNED</promise>` |
+| Step 6 | `<promise>FEATURE_ADR_PLANNED</promise>` |
+| Step 7 | `<promise>FEATURE_ADR_IMPLEMENTED</promise>` |
+| Step 8 | `<promise>FEATURE_ADR_VERIFIED</promise>` |
+
+## External Skills (loaded as needed)
+
+| Skill | Used In | Purpose |
+|-------|---------|---------|
+| explore | Step 1 | Requirements clarification |
+| problem-solver-enhanced | Step 3 | Trade-off analysis for ADR decisions |
+| frontend-design | Step 7 | UI implementation (if feature has UI) |
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Skip complexity assessment | Jump straight to coding | BLOCK — always run Step 0 |
+| Over-engineer S-tier | Run full pipeline for a config change | Router should classify as S |
+| Under-engineer XL-tier | Skip ADR/DDD for major refactor | Router should classify as XL |
+| ADR without alternatives | Only one option considered | Require ≥2 alternatives per ADR |
+| Architecture without ADR | Diagram before decisions | Step 5 requires Step 3 output |
+| Code without plan | Start coding without Step 6 | BLOCK — plan is mandatory |
+| No QE | Ship without testing | BLOCK — Step 8 is mandatory |
+
+## Checkpoint Format
+
+```
+═══════════════════════════════════════════════════════
+⏸️ STEP N/8: [Step Name] Complete
+<promise>[PROMISE_TAG]</promise>
+Tier: {COMPLEXITY_TIER} | Active Steps: {ACTIVE_STEPS}
+
+[2-3 line summary]
+Artifacts: [list] ✅
+
+• "ок" — next step
+• "углуби [section]" — elaborate
+• "[feedback]" — adjust
+═══════════════════════════════════════════════════════
+```