@dzhechkov/keysarium 1.1.1 → 1.2.0

package/templates/.claude/rules/background-workers.md

@@ -0,0 +1,72 @@
+# Background Workers Rules
+
+## When to Auto-Launch Workers
+
+| Trigger | Worker Type | Condition |
+|---------|------------|-----------|
+| Case completion | `consolidate` | After 3rd completed `/casarium` case in project |
+| Post-BTO test | `health-check` | After any `/bto-test` run (advisory, not enforced) |
+| Manual | Any | User runs `/workers start <type>` |
+
+Auto-launch triggers are ADVISORY. The system may suggest launching a worker but
+MUST wait for user confirmation before actually spawning a background agent.
+
+## Worker Isolation Rules
+
+1. Workers MUST only write to `.keysarium/workers/{worker_id}/` directory
+2. Workers MUST NOT modify files in `researches/` (active research data)
+3. Workers MUST NOT modify files in `features/` (active feature data)
+4. Workers MUST NOT modify files in `.claude/` (commands, rules, skills)
+5. Workers MUST NOT modify `CLAUDE.md`, `TOOLKIT_HARVEST.md`, or any root-level file
+6. Workers MAY read any file in the project for analysis purposes
+7. Exception: `export-brain` worker MAY write to `.keysarium/exports/` (standard export location)
+
+## Model Routing for Workers
+
+| Worker Type | Model | Rationale |
+|-------------|-------|-----------|
+| `consolidate` | sonnet | Pattern synthesis requires analytical reasoning |
+| `export-brain` | haiku | Primarily file reading and JSON assembly |
+| `health-check` | haiku | Structural checks, simple pattern matching |
+| `pattern-analysis` | sonnet | Trend analysis requires deeper reasoning |
+
+NEVER use opus for background workers -- workers perform routine tasks, not creative work.
+ALWAYS specify the model parameter when spawning a worker agent.
+
+## Concurrency Limits
+
+- Maximum concurrent workers: **3**
+- If limit reached, new worker requests MUST be rejected (not queued)
+- Rationale: prevent context exhaustion and ensure foreground responsiveness
+
+## Worker Naming Convention
+
+When spawning worker agents, use this naming format:
+```
+"Background Worker: {type} ({worker_id})"
+```
+
+Example: `"Background Worker: consolidate (wkr-20260301-143022-consolidate)"`
+
+## Worker Timeout
+
+- Workers are subject to the Agent tool's built-in timeout (~10 minutes)
+- Design workers to complete within this window
+- If a worker needs more time, it should checkpoint its progress and be re-launched
+
+## Registry Management
+
+- Only the `/workers` command (orchestrator) may write to `registry.json`
+- Workers write to their own `status.json` in their output directory
+- This prevents write conflicts between the orchestrator and workers
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Worker modifies research files | File write outside `.keysarium/workers/` | BLOCK -- enforce isolation |
+| Worker uses opus model | Model parameter check | Use haiku or sonnet per routing table |
+| More than 3 concurrent workers | Registry count check | Reject new worker start |
+| Worker spawns sub-agents | Instruction check in template | Templates explicitly forbid sub-agents |
+| Auto-launch without user consent | Missing user confirmation | Always ask before auto-launching |
+| Worker runs indefinitely | No progress updates | Workers must update status.json periodically |

package/templates/.claude/rules/dream-cycles.md

@@ -0,0 +1,90 @@
+# Dream Cycles Integration Rules
+
+## Auto-Trigger Rules
+
+When starting a new pipeline run (`/casarium` or `/feature-adr`), the orchestrator SHOULD check dream triggers:
+
+1. Read `.keysarium/insights/trigger-state.json`
+2. Evaluate triggers using the protocol in `lib/dream-engine.md`
+3. If any trigger is met, suggest to the user:
+   ```
+   Dream cycle trigger met ({reason}). Consider running /dream run for fresh insights.
+   ```
+4. This is ADVISORY only -- do not auto-launch without user confirmation
+5. If user declines, proceed normally
+
+### Trigger Check Timing
+
+- Check triggers at pipeline START (before Phase 0 or Step 0)
+- Do NOT check triggers mid-pipeline (would interrupt flow)
+- Do NOT check triggers on simple commands (/harvest, /brain-export, /learning-stats)
+
+## Insight Application Rules
+
+### At /casarium Phase 0 (Discovery)
+
+1. After domain detection, check `.keysarium/insights/` for the most recent dream result
+2. Filter insights by detected domain
+3. For each relevant insight, apply:
+   - **Performance insights**: Adjust time budget recommendations for flagged phases
+   - **Effectiveness insights**: Note skill preferences in the case brief
+   - **Preference insights**: Flag preferred CJM variants for Phase 2.5
+   - **Anti-pattern insights**: Add explicit warnings to the case brief
+4. Log loaded insights: "Applied {count} dream insights for {domain} domain"
+
+### At /casarium Phase 2 (Research)
+
+If a performance insight flags Phase 2 as problematic for the current domain:
+- Log a warning: "Dream insight: Phase 2 is historically challenging for {domain}. Extra attention recommended."
+- This is informational only -- does not change the research protocol
+
+### At /feature-adr Step 0 (Complexity Router)
+
+Dream insights are NOT applied to feature-adr (different pipeline, different context).
+
+## Retention Rules
+
+1. Maximum 10 dream result files in `.keysarium/insights/`
+2. Retention is enforced at the END of each dream cycle (Step 5)
+3. Retention is also enforced by `/dream clear`
+4. `trigger-state.json` is NEVER deleted by retention (it is state, not a result)
+5. Dream result files are named `dream-{YYYYMMDD}-{HHmmss}.json` for chronological sorting
+
+## Integration with memory_store()
+
+After writing a reward record via `memory_store()`, the system SHOULD:
+1. Attempt to read `.keysarium/insights/trigger-state.json`
+2. If it exists, increment `records_since_last_dream` and write back
+3. If it does not exist, skip silently (dream cycles not yet initialized)
+4. If write fails, log warning and continue (non-critical)
+
+This integration is ADVISORY -- memory_store() must succeed even if trigger state update fails.
+
+## Integration with Event Triggers
+
+### Quality Gate Failure
+
+When a BTO quality gate fails (Layer 0 rejection after 3 retries):
+1. Append event to `trigger-state.json`:
+   ```json
+   { "event_type": "quality_gate_failure", "timestamp": "...", "details": "BTO Layer 0 failed 3x" }
+   ```
+2. Suggest running `/dream run` to analyze the failure pattern
+
+### Case Completion
+
+When a `/casarium` run completes (Phase 6 packaging done):
+1. Append event to `trigger-state.json`:
+   ```json
+   { "event_type": "case_completion", "timestamp": "...", "details": "Completed {slug}" }
+   ```
+2. If `records_since_last_dream >= 10` (half of volume threshold), suggest a dream run
+
+## Model Routing
+
+| Operation | Model | Rationale |
+|-----------|-------|-----------|
+| Dream cycle execution | sonnet | Analytical pattern detection |
+| Trigger evaluation | N/A | Deterministic JSON operations |
+| Insight display | N/A | File reading and formatting |
+| Status display | N/A | File reading and formatting |

package/templates/.claude/rules/feature-adr-conventions.md

@@ -0,0 +1,82 @@
+# Feature ADR Conventions
+
+## When to Use /feature-adr vs Other Commands
+
+| Situation | Command |
+|-----------|---------|
+| Implementing a software feature | `/feature-adr` |
+| Researching an AI case for hackathon | `/casarium` |
+| Solving a complex problem (no code) | `/solve` |
+| Designing architecture only (no code) | `/architecture-phase` |
+| Building a new skill/command | `/bto-build` |
+
+## Output Directory
+
+All `/feature-adr` artifacts go into `features/<feature-slug>/`.
+NEVER create feature artifacts in the project root or in `researches/`.
+
+`researches/` is for `/casarium` pipeline only.
+`features/` is for `/feature-adr` pipeline only.
+
+## Slug Naming
+
+- Format: `kebab-case`, Latin characters only
+- Max length: 40 characters
+- Examples: `add-user-auth`, `refactor-payment-flow`, `migrate-to-postgres`
+- NO dates, NO ticket numbers in slug (put those in the artifact files)
+
+## Artifact Naming
+
+All artifacts use numbered prefix matching their step:
+
+```
+00_complexity_assessment.md
+01_requirements.md
+02_research.md
+03_adr/001-{decision-slug}.md
+04_domain_model.md
+05_architecture.md
+06_implementation_plan.md
+07_code_changes/change_manifest.md
+08_qe_report.md
+```
+
+## Complexity Tier Rules
+
+- Tier is determined by Step 0 (Complexity Router) — never guess
+- User can override tier at Checkpoint 0
+- Once confirmed, tier determines which steps run
+- Tier CANNOT change mid-pipeline (restart if scope changes significantly)
+
+## Integration with Existing Pipeline
+
+`/feature-adr` is independent from the Casarium pipeline.
+It does NOT use:
+- Phase numbering (Phase 0-6)
+- Research artifacts (00_product_discovery.md, etc.)
+- CJM prototypes
+- Presentation generation
+
+It DOES share:
+- Skills (`explore`, `problem-solver-enhanced`, `frontend-design`)
+- Agent swarm patterns
+- Checkpoint protocol
+- Promise tag system
+- Model routing rules
+
+## Feature Lifecycle
+
+```
+/feature-adr [description]
+  → Step 0: classify
+  → Steps 1-5: design (per tier)
+  → Step 6: plan
+  → Step 7: code
+  → Step 8: QE
+  → Done: README.md + code changes in repo
+```
+
+After completion:
+- Code changes live in the actual codebase (not just in `features/`)
+- `features/<slug>/` contains the design artifacts (ADRs, diagrams, reports)
+- These artifacts serve as documentation for the feature

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