@dzhechkov/keysarium 1.1.2 → 1.3.0

package/templates/lib/judge-attestation.md

@@ -0,0 +1,322 @@
+# Judge Attestation Protocol
+
+> Cryptographic proof of BTO judge isolation via SHA-256 hash chain attestations.
+
+## Purpose
+
+This protocol defines how BTO judges (Domain Expert, Critic, Completeness Auditor) create cryptographic attestations proving their evaluations were performed independently. Each judge records a hash of its evaluation before seeing other judges' scores. The attestations are chained to provide ordering proof.
+
+## Constants
+
+```
+NULL_HASH = "0000000000000000000000000000000000000000000000000000000000000000"
+ATTESTATION_FILE = ".judge-attestations.json"
+HASH_PREFIX = "sha256:"
+STANDARD_PANEL_SIZE = 3
+HIGH_STAKES_PANEL_SIZE = 5
+```
+
+## Section 1: Attestation Creation
+
+### Hash Input Construction
+
+Each judge's evaluation hash is computed from a deterministic concatenation of:
+
+```
+evaluation_hash = SHA-256(judge_id + "|" + artifact_hash + "|" + score + "|" + rationale_summary)
+```
+
+The pipe character `|` serves as a delimiter to prevent ambiguity in concatenation.
+
+**Fields:**
+- `judge_id`: One of `"domain-expert"`, `"critic"`, `"completeness-auditor"` (or `"meta-judge"` for escalation)
+- `artifact_hash`: SHA-256 hash of the artifact being evaluated (computed before evaluation starts)
+- `score`: The numeric score as a string with one decimal place (e.g., `"8.2"`)
+- `rationale_summary`: First 500 characters of the judge's rationale text, trimmed of leading/trailing whitespace
+
+### Computing the Artifact Hash
+
+Before any judge starts evaluation, compute the artifact hash:
+
+```bash
+ARTIFACT_HASH=$(${SHA_CMD} "path/to/artifact.md" | awk '{print $1}')
+```
+
+This hash is shared with all judges and recorded in each attestation. It proves all judges evaluated the same artifact.
+
+### Computing the Evaluation Hash
+
+After a judge completes its evaluation:
+
+```bash
+JUDGE_ID="domain-expert"
+ARTIFACT_HASH="<computed above>"
+SCORE="8.2"
+RATIONALE_SUMMARY="<first 500 chars of rationale>"
+
+EVAL_HASH=$(printf '%s' "${JUDGE_ID}|${ARTIFACT_HASH}|${SCORE}|${RATIONALE_SUMMARY}" | ${SHA_CMD} | awk '{print $1}')
+```
+
+**Important:** The rationale_summary must be trimmed to exactly 500 characters (or fewer if the rationale is shorter) to ensure deterministic reproduction during verification.
+
+## Section 2: Chain Linking
+
+### Attestation Order
+
+Judges are recorded in a fixed order within each evaluation round:
+
+1. Domain Expert (first, previous = NULL_HASH)
+2. Critic (second, previous = Domain Expert's evaluation_hash)
+3. Completeness Auditor (third, previous = Critic's evaluation_hash)
+
+For a 5-judge high-stakes panel:
+4. Additional Expert (fourth, previous = Auditor's evaluation_hash)
+5. Tiebreaker (fifth, previous = Additional Expert's evaluation_hash)
+
+### Chain Link Protocol
+
+```bash
+# Judge 1 (Domain Expert)
+PREV_ATTESTATION_HASH="${NULL_HASH}"
+# ... compute evaluation_hash_1 ...
+# Record attestation with previous = NULL_HASH
+
+# Judge 2 (Critic)
+PREV_ATTESTATION_HASH="${EVAL_HASH_1}"
+# ... compute evaluation_hash_2 ...
+# Record attestation with previous = evaluation_hash_1
+
+# Judge 3 (Completeness Auditor)
+PREV_ATTESTATION_HASH="${EVAL_HASH_2}"
+# ... compute evaluation_hash_3 ...
+# Record attestation with previous = evaluation_hash_2
+```
+
+### Ordering Note
+
+The chain records the ORDER in which attestations were finalized, not the order in which judges started evaluating. Since judges evaluate in parallel but record sequentially, the chain proves:
+- Each attestation was recorded after the previous one
+- The evaluation_hash was computed from the judge's OWN data only
+- The previous_attestation_hash links to the preceding record (not to the preceding judge's score)
+
+## Section 3: Isolation Verification
+
+### Verification Algorithm
+
+```
+1. Load .judge-attestations.json
+2. For each evaluation round:
+   a. Verify artifact_hash matches across all attestations
+   b. For each attestation (index i):
+      i.   Reconstruct evaluation_hash from (judge_id, artifact_hash, score, rationale_summary)
+      ii.  Compare reconstructed hash with stored evaluation_hash
+      iii. If i == 0: verify previous_attestation_hash == NULL_HASH
+      iv.  If i > 0: verify previous_attestation_hash == attestations[i-1].evaluation_hash
+      v.   Verify timestamp > attestations[i-1].timestamp (if i > 0)
+3. Produce verification report
+```
+
+### Isolation Proof Logic
+
+The isolation proof works as follows:
+
+1. **Hash Independence:** Each evaluation_hash is computed from `judge_id|artifact_hash|score|rationale`. If a judge had seen another judge's score, it would not affect its own hash computation -- but it would be detectable if the rationale text references specific scores from other judges.
+
+2. **Chain Integrity:** The previous_attestation_hash links attestations in order but does NOT include other judges' scores in the hash input. This means the chain proves ORDER but the evaluation content is provably independent.
+
+3. **Timestamp Monotonicity:** Timestamps must be strictly increasing. If Judge B's timestamp is BEFORE Judge A's, but Judge B's previous_attestation_hash points to Judge A, then something is wrong.
+
+### Verification Script
+
+```bash
+python3 << 'VERIFY_ATTESTATION'
+import json, subprocess, sys
+
+NULL_HASH = "0" * 64
+
+def sha256(content):
+    result = subprocess.run(
+        ["sha256sum"],
+        input=content.encode(),
+        capture_output=True
+    )
+    if result.returncode != 0:
+        result = subprocess.run(
+            ["shasum", "-a", "256"],
+            input=content.encode(),
+            capture_output=True
+        )
+    return result.stdout.decode().split()[0]
+
+DIR = sys.argv[1] if len(sys.argv) > 1 else "."
+
+with open(f"{DIR}/.judge-attestations.json") as f:
+    data = json.load(f)
+
+for eval_round in data.get("evaluations", [data]):
+    attestations = eval_round.get("attestations", [])
+    artifact_hash = eval_round.get("artifact_hash", "")
+    violations = []
+
+    for i, att in enumerate(attestations):
+        # Reconstruct evaluation hash
+        hash_input = f"{att['judge_id']}|{artifact_hash}|{att['score']}|{att.get('rationale_summary', '')}"
+        expected = sha256(hash_input)
+        actual = att["evaluation_hash"].replace("sha256:", "")
+
+        if expected != actual:
+            violations.append(f"Judge {att['judge_id']}: evaluation_hash mismatch")
+
+        # Verify chain link
+        if i == 0:
+            expected_prev = NULL_HASH
+        else:
+            expected_prev = attestations[i-1]["evaluation_hash"].replace("sha256:", "")
+
+        actual_prev = att["previous_attestation_hash"].replace("sha256:", "")
+        if expected_prev != actual_prev:
+            violations.append(f"Judge {att['judge_id']}: chain link broken")
+
+    if not violations:
+        print(f"PASS: All {len(attestations)} judge attestations verified. Isolation confirmed.")
+    else:
+        print(f"FAIL: {len(violations)} violations detected:")
+        for v in violations:
+            print(f"  - {v}")
+
+VERIFY_ATTESTATION
+```
+
+## Section 4: File Format
+
+### .judge-attestations.json Schema
+
+```json
+{
+  "evaluations": [
+    {
+      "evaluation_id": "string — unique ID for this evaluation round",
+      "artifact_path": "string — path to the evaluated artifact",
+      "artifact_hash": "string — sha256:<hex> of the artifact content",
+      "panel_size": "integer — 3 (standard) or 5 (high-stakes)",
+      "started_at": "ISO-8601 — when evaluation round began",
+      "completed_at": "ISO-8601 — when last attestation recorded",
+      "attestations": [
+        {
+          "judge_id": "string — domain-expert|critic|completeness-auditor",
+          "score": "float — 0.0-10.0",
+          "rationale_summary": "string — first 500 chars of rationale",
+          "evaluation_hash": "string — sha256:<hex>",
+          "timestamp": "ISO-8601 — when attestation was recorded",
+          "previous_attestation_hash": "string — sha256:<hex> or null hash"
+        }
+      ],
+      "final_score": "float — weighted average",
+      "weights": {
+        "domain-expert": 0.4,
+        "critic": 0.3,
+        "completeness-auditor": 0.3
+      }
+    }
+  ]
+}
+```
+
+### Example Attestation File
+
+```json
+{
+  "evaluations": [
+    {
+      "evaluation_id": "bto-eval-2026-03-01T12:00:00Z",
+      "artifact_path": ".claude/skills/explore/SKILL.md",
+      "artifact_hash": "sha256:abc123def456789012345678901234567890123456789012345678901234fedc",
+      "panel_size": 3,
+      "started_at": "2026-03-01T12:00:00Z",
+      "completed_at": "2026-03-01T12:01:45Z",
+      "attestations": [
+        {
+          "judge_id": "domain-expert",
+          "score": 8.2,
+          "rationale_summary": "Strong SKILL.md with clear protocol steps. References directory provides good examples...",
+          "evaluation_hash": "sha256:111222333444555666777888999000aaabbbcccdddeeefff000111222333444555",
+          "timestamp": "2026-03-01T12:00:30Z",
+          "previous_attestation_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
+        },
+        {
+          "judge_id": "critic",
+          "score": 7.5,
+          "rationale_summary": "Missing edge case handling for multi-language inputs. Error recovery protocol unclear...",
+          "evaluation_hash": "sha256:222333444555666777888999000aaabbbcccdddeeefff000111222333444555666",
+          "timestamp": "2026-03-01T12:01:00Z",
+          "previous_attestation_hash": "sha256:111222333444555666777888999000aaabbbcccdddeeefff000111222333444555"
+        },
+        {
+          "judge_id": "completeness-auditor",
+          "score": 8.0,
+          "rationale_summary": "All required sections present. References directory has 3 examples. Missing: performance benchmarks...",
+          "evaluation_hash": "sha256:333444555666777888999000aaabbbcccdddeeefff000111222333444555666777",
+          "timestamp": "2026-03-01T12:01:30Z",
+          "previous_attestation_hash": "sha256:222333444555666777888999000aaabbbcccdddeeefff000111222333444555666"
+        }
+      ],
+      "final_score": 7.94,
+      "weights": {
+        "domain-expert": 0.4,
+        "critic": 0.3,
+        "completeness-auditor": 0.3
+      }
+    }
+  ]
+}
+```
+
+## Section 5: Integration with BTO Pipeline
+
+### When to Create Attestations
+
+Attestations are created during **BTO Layer 2 evaluation** (the judge panel stage):
+
+1. **Before panel starts:** Compute `artifact_hash` of the artifact being evaluated
+2. **After each judge completes:** Create attestation record with evaluation_hash
+3. **After all judges complete:** Write `.judge-attestations.json`
+4. **If meta-judge is invoked:** Add a 4th attestation with `judge_id: "meta-judge"`
+
+### Integration Points
+
+| BTO Stage | Attestation Action |
+|-----------|-------------------|
+| Layer 0 (structural) | No attestation needed (deterministic checks) |
+| Layer 1 (semantic) | No attestation needed (single haiku agent) |
+| Layer 2 (judge panel) | Create attestation set with 3 attestations |
+| Meta-judge (escalation) | Append meta-judge attestation to the set |
+| Optimization rounds | Create new attestation set per round's final evaluation |
+
+### Disagreement Detection Enhancement
+
+With attestations, disagreement detection gains cryptographic backing:
+
+```
+If max_score - min_score > 3.0:
+  1. Verify all attestations are valid (no tampering)
+  2. Verify isolation (no judge influenced another)
+  3. If isolation verified: escalate to meta-judge (genuine disagreement)
+  4. If isolation violated: flag conformity collapse warning
+```
+
+## Section 6: Meta-Judge Attestation
+
+When the meta-judge is invoked (disagreement > 3 points), it creates its own attestation:
+
+```json
+{
+  "judge_id": "meta-judge",
+  "score": 7.8,
+  "rationale_summary": "Disagreement between domain-expert (8.5) and critic (5.2) on dimension 'completeness'...",
+  "evaluation_hash": "sha256:...",
+  "timestamp": "2026-03-01T12:02:00Z",
+  "previous_attestation_hash": "sha256:<last judge's eval hash>"
+}
+```
+
+The meta-judge's rationale MAY reference other judges' scores (it has access to them for arbitration). This is expected and does not violate isolation -- the meta-judge is explicitly a synthesizer, not an independent evaluator.

package/templates/lib/memory-protocol.md

@@ -0,0 +1,344 @@
+# Memory Protocol -- Reward-Calibrated Learning
+
+Core protocol for persistent memory in the Keysarium pipeline. Provides `memory_query()` before tasks and `memory_store()` after tasks.
+
+**Protocol version: 1.1** — adds 2-tier index, record lifecycle (HOT/WARM/COLD/PURGE), and brain container manifest.
+
+## Memory Namespace
+
+All memory files live in `.keysarium/memory/`:
+
+```
+.keysarium/memory/
+├── config.json                                    ← Global configuration
+├── index.json                                     ← 2-tier index (v1.1)
+├── _patterns/
+│   └── domain-patterns.json                       ← Detected domain patterns
+├── _stats/
+│   ├── reward-summary.json                        ← Aggregate statistics
+│   └── imported-baselines.json                    ← Imported reward baselines
+├── {domain}/                                      ← banking | retail | enterprise | healthcare
+│   ├── {case-slug}/
+│   │   └── {phase}_{timestamp}.json               ← HOT/WARM reward records
+│   └── _archive/                                  ← COLD compressed records (v1.1)
+│       └── {case-slug}/
+│           └── {phase}_{timestamp}.json            ← Archived records
+```
+
+## Configuration
+
+### config.json (auto-created with defaults on first access)
+
+```json
+{
+  "version": "1.1",
+  "retention_days": 90,
+  "max_results_per_query": 10,
+  "enabled": true,
+  "known_domains": ["banking", "retail", "enterprise", "healthcare"],
+  "reward_levels": {
+    "excellent": 1.0,
+    "good": 0.7,
+    "needs_work": 0.3,
+    "failed": 0.0
+  },
+  "tier_hot_days": 30,
+  "tier_warm_days": 90,
+  "tier_cold_days": 180
+}
+```
+
+**Tier fields (v1.1):** If `tier_hot_days` is absent, fall back to v1.0 behavior (flat `retention_days` with no tiering). When present, `retention_days` is ignored in favor of the tier thresholds.
+
+## Index File (v1.1)
+
+The index provides a compact catalog of all records, enabling targeted reads instead of full directory scans.
+
+### index.json Schema
+
+```json
+{
+  "version": "1.0",
+  "last_updated": "2026-03-02T14:00:00Z",
+  "record_count": 47,
+  "by_domain": {
+    "banking": {
+      "count": 23,
+      "slugs": ["case-a", "case-b"],
+      "avg_reward": 0.82
+    }
+  },
+  "by_phase": {
+    "phase-0": { "count": 8, "avg_reward": 0.91 },
+    "phase-2": { "count": 12, "avg_reward": 0.65 }
+  },
+  "by_skill": {
+    "goap-research-ed25519": { "count": 10, "avg_reward": 0.78 }
+  },
+  "records": {
+    "bank_kc_automation_phase-2_2026-03-01T12-30-00": {
+      "domain": "banking",
+      "phase": "phase-2",
+      "slug": "bank_kc_automation",
+      "reward": 0.7,
+      "skill": "goap-research-ed25519",
+      "tier": "hot",
+      "file": "banking/bank_kc_automation/phase-2_2026-03-01T12-30-00.json",
+      "expires_at": "2026-08-28T12:30:00Z"
+    }
+  }
+}
+```
+
+### Index Behavior
+
+- **Created:** On first `memory_store()` call when tier config is present (or `index.json` already exists)
+- **Updated:** On every `memory_store()`, archive, and purge operation
+- **Fallback:** If missing, `memory_query()` uses v1.0 full-scan algorithm
+- **Rebuild:** If corrupted, delete `index.json` — it will be recreated on next `memory_store()`
+
+## Protocol: memory_query(context)
+
+Call at the **start** of each pipeline phase to load relevant historical patterns.
+
+### Input
+
+```json
+{
+  "phase": "phase-2",
+  "domain": "banking",
+  "slug": "bank_kc_automation",
+  "skill": "goap-research-ed25519"
+}
+```
+
+### Algorithm
+
+1. **Check enabled:** Read `.keysarium/memory/config.json`. If `enabled` is false or directory does not exist, return empty list.
+2. **Read index (v1.1):** If `.keysarium/memory/index.json` exists, read it and filter `records` entries by `domain` + `phase`. Go to step 2a. If index does not exist, fall back to step 3 (v1.0 full scan).
+   - 2a. **Index hit:** If filtered record count ≤ `max_results_per_query`, read only those files by `file` path (targeted read). Go to step 4.
+   - 2b. **Index overflow:** If filtered count > limit, rank by `reward` from index entries, select top-N `file` paths, read those files. Go to step 4.
+3. **Full scan (fallback):** Construct `.keysarium/memory/{domain}/` (scan all slugs). Read all `{phase}_*.json` files matching the requested phase.
+4. **Filter expired:** Exclude records where `expires_at < current_date`.
+5. **Archive old records (v1.1):** If tier config is present, check record ages. For records older than `tier_warm_days`:
+   - Read full record
+   - Generate `summary` from `reward_reason` + `outcome.checkpoint_response` (first 200 chars)
+   - Write compressed record to `.keysarium/memory/{domain}/_archive/{slug}/{filename}`
+   - Delete original file from active directory
+   - Update `index.json`: set `tier` to `"cold"`, update `file` path
+   - Log: "Archived {count} records to cold storage in {domain}"
+6. **Purge ancient records (v1.1):** Delete records from `_archive/` older than `tier_cold_days`. In v1.0 mode, delete records where `expires_at < current_date`. Update `index.json`. Log: "Purged {count} expired records from {domain}"
+7. **Sort:** By `reward` DESC, then `timestamp` DESC. HOT and WARM records first; COLD records included only if result count < `max_results_per_query`.
+8. **Limit:** Return top `max_results_per_query` records (default 10).
+9. **Enrich:** Also load `.keysarium/memory/_patterns/domain-patterns.json` for matching domain patterns.
+
+### Output
+
+```json
+{
+  "records": [
+    {
+      "case_slug": "bank_loan_approval",
+      "phase": "phase-2",
+      "reward": 1.0,
+      "reward_label": "excellent",
+      "skill_used": "goap-research-ed25519",
+      "outcome_summary": "Research completed with all claims verified...",
+      "timestamp": "2026-02-15T14:30:00Z"
+    }
+  ],
+  "patterns": [
+    {
+      "pattern_id": "banking-phase2-slow",
+      "description": "Banking cases take 2x longer in Phase 2 due to regulatory research",
+      "confidence": 0.85,
+      "actionable_advice": "Allocate extra time budget for Phase 2 in banking domain"
+    }
+  ],
+  "count": 3,
+  "domain": "banking"
+}
+```
+
+### Usage in Phase
+
+After calling `memory_query()`, the agent should:
+1. Log: "Loaded {count} historical patterns for {phase} in {domain} domain"
+2. If `records` is non-empty, review the top 3 records for relevant approaches
+3. If `patterns` is non-empty, apply actionable advice to current phase execution
+4. If both are empty (first run), proceed normally
+
+## Protocol: memory_store(result, reward)
+
+Call at each **checkpoint** after the user responds, to persist the phase outcome with a reward score.
+
+### Input
+
+```json
+{
+  "case_slug": "bank_kc_automation",
+  "domain": "banking",
+  "phase": "phase-2",
+  "phase_name": "Research",
+  "skill_used": "goap-research-ed25519",
+  "reward": 0.7,
+  "reward_label": "good",
+  "reward_reason": "User requested minor edits to competitor analysis section",
+  "context": {
+    "phase_number": 2,
+    "domain_detected": "banking",
+    "upstream_promises": ["DISCOVERY_COMPLETE", "CASE_EXPLORED"],
+    "patterns_loaded": 3,
+    "time_budget_pct": 15.0,
+    "agent_count": 3
+  },
+  "outcome": {
+    "artifacts_created": ["02_research_findings.md"],
+    "checkpoint_response": "ok, but expand the FinTech competitor section",
+    "iterations": 2,
+    "promise_emitted": "RESEARCH_PARANOID_PASSED"
+  }
+}
+```
+
+### Algorithm
+
+1. **Ensure directory exists:** Create `.keysarium/memory/{domain}/{slug}/` if it does not exist.
+2. **Build record:** Construct full RewardRecord JSON from input.
+3. **Compute expires_at:** If tier config is present, use `tier_cold_days` (default 180 days). Otherwise, use `retention_days` (default 90 days). Formula: `current_date + threshold`.
+4. **Generate filename:** `{phase}_{ISO-timestamp}.json` (e.g., `phase-2_2026-03-01T12-30-00.json`).
+5. **Write file:** Write JSON to `.keysarium/memory/{domain}/{slug}/{filename}`.
+6. **Update index (v1.1):** Read `.keysarium/memory/index.json` (or create if absent and tier config is present):
+   - Add record entry to `records` map: key = record id, value = `{domain, phase, slug, reward, skill, tier: "hot", file, expires_at}`
+   - Increment `record_count`
+   - Update `by_domain` aggregate: increment count, add slug if new, recalculate `avg_reward`
+   - Update `by_phase` aggregate: increment count, recalculate `avg_reward`
+   - Update `by_skill` aggregate: increment count, recalculate `avg_reward`
+   - Set `last_updated` to current timestamp
+   - Write updated `index.json`
+7. **Log:** "Stored reward {reward} ({reward_label}) for {phase} of {slug}"
+
+### RewardRecord JSON Schema
+
+```json
+{
+  "id": "bank_kc_automation_phase-2_2026-03-01T12-30-00",
+  "version": "1.1",
+  "timestamp": "2026-03-01T12:30:00Z",
+  "case_slug": "bank_kc_automation",
+  "domain": "banking",
+  "phase": "phase-2",
+  "phase_name": "Research",
+  "skill_used": "goap-research-ed25519",
+  "reward": 0.7,
+  "reward_label": "good",
+  "reward_reason": "User requested minor edits to competitor analysis section",
+  "context": {
+    "phase_number": 2,
+    "domain_detected": "banking",
+    "upstream_promises": ["DISCOVERY_COMPLETE", "CASE_EXPLORED"],
+    "patterns_loaded": 3,
+    "time_budget_pct": 15.0,
+    "agent_count": 3
+  },
+  "outcome": {
+    "artifacts_created": ["02_research_findings.md"],
+    "checkpoint_response": "ok, but expand the FinTech competitor section",
+    "iterations": 2,
+    "promise_emitted": "RESEARCH_PARANOID_PASSED"
+  },
+  "promise_tag": "RESEARCH_PARANOID_PASSED",
+  "expires_at": "2026-08-28T12:30:00Z"
+}
+```
+
+## Record Lifecycle (v1.1)
+
+Records transition through tiers based on age:
+
+| Tier | Age Range | Location | Fields |
+|------|-----------|----------|--------|
+| **HOT** | 0 – 30 days | `{domain}/{slug}/` | All fields |
+| **WARM** | 30 – 90 days | `{domain}/{slug}/` | All fields (deprioritized in search) |
+| **COLD** | 90 – 180 days | `{domain}/_archive/{slug}/` | Compressed (see below) |
+| **PURGE** | > 180 days | Deleted | — |
+
+Tier thresholds are configurable via `config.json` fields: `tier_hot_days`, `tier_warm_days`, `tier_cold_days`.
+
+### COLD Record Schema (compressed)
+
+```json
+{
+  "id": "bank_kc_automation_phase-2_2026-01-01T12-00-00",
+  "phase": "phase-2",
+  "domain": "banking",
+  "slug": "bank_kc_automation",
+  "reward": 0.7,
+  "reward_label": "good",
+  "skill_used": "goap-research-ed25519",
+  "promise_tag": "RESEARCH_PARANOID_PASSED",
+  "summary": "User requested minor edits to competitor analysis section. ok, but expand the FinTech competitor section",
+  "archived_at": "2026-03-02T14:00:00Z",
+  "original_timestamp": "2026-01-01T12:00:00Z"
+}
+```
+
+### Backward Compatibility
+
+If `tier_hot_days` is NOT present in `config.json`, the lifecycle system is disabled. Records use the v1.0 flat `retention_days` for expiration. No archiving occurs.
+
+## Reward Assignment Rules
+
+The reward score is determined by the user's response at the checkpoint:
+
+| User Behavior | Reward | Label | Detection |
+|---------------|--------|-------|-----------|
+| Says "ok" / "ок" / proceeds to next phase immediately | 1.0 | excellent | Exact match or single-word approval |
+| Requests minor adjustments ("углуби X", small edits to one section) | 0.7 | good | Feedback is scoped to one area, does not change direction |
+| Requests significant rework (multiple sections, changed approach, re-research) | 0.3 | needs_work | Feedback affects multiple areas or changes phase direction |
+| Restarts phase entirely / says result is unusable / requests complete redo | 0.0 | failed | Phase restarts from scratch |
+
+### Edge Cases
+
+- **"углуби [section]"** = 0.7 (deepening is enhancement, not failure)
+- **Multiple rounds of minor feedback** = 0.7 on first round, 0.3 if third+ round
+- **Positive feedback with minor note** ("great, just fix the typo in section 3") = 1.0
+- **No explicit response** (session ends) = do not store (no record created)
+
+## Error Handling
+
+| Error | Behavior |
+|-------|----------|
+| `.keysarium/memory/` does not exist | `memory_query()` returns empty; `memory_store()` creates directory |
+| `config.json` missing | Use defaults (90 days, 10 results, enabled) |
+| Malformed JSON file | Skip that record, log warning, continue |
+| Write fails (permissions, disk) | Log error, continue pipeline without storing |
+| Domain not in `known_domains` | Use "unknown" as domain directory |
+| `index.json` corrupted | Delete and rebuild on next `memory_store()` call |
+| Archive directory write fails | Log warning, keep record in active directory |
+
+## Integration with Brain Export
+
+When `/brain-export` runs, it should include a `"reward_data"` section:
+
+```json
+{
+  "reward_data": {
+    "total_records": 42,
+    "domains": ["banking", "retail"],
+    "phase_averages": {
+      "phase-0": 0.85,
+      "phase-1": 0.92,
+      "phase-2": 0.65,
+      "phase-2.5": 0.78,
+      "phase-3": 0.71,
+      "phase-4": 0.89,
+      "phase-5": 0.74
+    },
+    "top_patterns": [],
+    "exported_from": ".keysarium/memory/"
+  }
+}
+```
+
+Individual records are NOT exported (too voluminous). Only aggregates and patterns are included.