@dzhechkov/harness-core 0.3.90 → 0.3.94

package/src/statusline.ts

@@ -37,6 +37,8 @@ export interface FeatureAdrState {
   readonly recalled: number;
   /** How many NEW patterns this run STORED back into the pool. */
   readonly stored: number;
+  /** How many candidate lessons reinforced an existing pattern instead of writing a duplicate. */
+  readonly reinforced?: number;
   /** ISO timestamp of the write — drives the freshness window on the render path. */
   readonly ts: string;
   /** Optional run mode (e.g. "reference", "full-qe", "full-qe-extended"). */
@@ -181,6 +183,7 @@ export function readFeatureAdrState(projectRoot: string, now: number = Date.now(
       pool: num(parsed.pool),
       recalled: num(parsed.recalled),
       stored: num(parsed.stored),
+      ...(num(parsed.reinforced) > 0 ? { reinforced: num(parsed.reinforced) } : {}),
       ts: parsed.ts,
       ...(typeof parsed.mode === 'string' && parsed.mode.length > 0 ? { mode: parsed.mode } : {}),
     };
@@ -196,6 +199,7 @@ export interface WriteFeatureAdrStateInput {
   readonly step: string;
   readonly recalled: number;
   readonly stored: number;
+  readonly reinforced?: number;
   readonly mode?: string;
 }
 
@@ -225,6 +229,7 @@ export function writeFeatureAdrState(
     pool,
     recalled: Number.isFinite(input.recalled) ? input.recalled : 0,
     stored: Number.isFinite(input.stored) ? input.stored : 0,
+    ...(input.reinforced !== undefined && Number.isFinite(input.reinforced) ? { reinforced: input.reinforced } : {}),
     ts: new Date(now).toISOString(),
     ...(input.mode !== undefined && input.mode.length > 0 ? { mode: input.mode } : {}),
   };

package/src/usage.ts

@@ -0,0 +1,289 @@
+/**
+ * `dz usage` data source — a READONLY, never-throw, best-effort estimate of Claude SESSION
+ * (active 5h-block) and WEEKLY (rolling 7d) token usage, aggregated from the local Claude Code
+ * transcript files under `~/.claude/projects/<munged>/<session>.jsonl`.
+ *
+ * ## Honest-uncertainty contract (LOAD-BEARING — NFR-4)
+ *
+ * These percentages are **ESTIMATES** derived by aggregating local transcript token counts against
+ * a USER-CONFIGURED limit. There is **no official usage API** being consulted — this is a fuel
+ * gauge built from the flow meter, not a tank sensor. Therefore:
+ *
+ * - Every payload carries `estimated: true` so a consumer can NEVER mistake it for ground truth.
+ * - When a limit is **unconfigured** (`.dz/config.json` has no `memory.usage.sessionTokenLimit` /
+ *   `weeklyTokenLimit`), the corresponding `pct` is `null` — **unknown, never 0, never a guess**.
+ * - **Calibration protocol (observed-exhaustion):** when a real limit-hit occurs at an estimated
+ *   `X%`, scale the configured limit by `X/100` so the next estimate lines up with reality. The
+ *   4 token fields are summed with equal weight; the relative weighting (cache-read tokens
+ *   dominate real transcripts) is absorbed into the calibrated limit value.
+ *
+ * ## Statusline discipline (NFR-1)
+ *
+ * Modeled on {@link ./statusline.ts} and {@link ./vector-tier.ts}'s `readVectorEngineMode`:
+ * - **never-throw** — any error (missing `~/.claude/projects`, corrupt jsonl line, missing/corrupt
+ *   config, garbled usage object) collapses to a value with `null` pcts, never an exception.
+ * - **readonly** — zero writes/appends/mkdir/unlink anywhere (the optional aggregate cache in
+ *   arch §2.2(6) is DEFERRED — v1 ships with zero writes so READONLY is trivially true).
+ * - **<100ms steady-state** via an `mtime` prefilter: a file whose `mtime` is older than the weekly
+ *   window cannot contribute and is skipped WITHOUT opening it; only files touched inside the
+ *   session window are line-parsed for the active block.
+ * - **injectable clock** — `computeUsage(root, now?)` takes an optional `now` (ms epoch) so all
+ *   window math is deterministic under test.
+ *
+ * @packageDocumentation
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const HOUR_MS = 60 * 60 * 1000;
+const SESSION_BLOCK_MS = 5 * HOUR_MS; // ccusage 5h-block
+const WEEK_MS = 7 * 24 * HOUR_MS; // rolling 7-day weekly window
+// mtime prefilter slack (+1h) — guards against clock skew between the writer and this reader
+// (a file with a slightly-stale mtime that is actually in-window must not be dropped).
+const MTIME_SLACK_MS = HOUR_MS;
+
+/** Optional, plan-dependent calibration limits from `.dz/config.json`. Absent ⇒ pct is `null`. */
+export interface UsageLimits {
+  readonly sessionTokenLimit?: number;
+  readonly weeklyTokenLimit?: number;
+}
+
+/** A never-throw usage estimate. `estimated` is ALWAYS `true` (honest-uncertainty marker). */
+export interface UsageEstimate {
+  /** Active 5h-block token total (all projects). `0` when there is no active block. */
+  readonly sessionTokens: number;
+  /** Rolling 7d token total (all projects). */
+  readonly weeklyTokens: number;
+  /** `null` ⇔ `sessionTokenLimit` unconfigured (unknown — never 0). */
+  readonly sessionPct: number | null;
+  /** `null` ⇔ `weeklyTokenLimit` unconfigured (unknown — never 0). */
+  readonly weeklyPct: number | null;
+  /** ISO — active block start + 5h; `null` when there is no active block. */
+  readonly sessionResetsAt: string | null;
+  /** ISO — oldest in-window sample ts + 7d (estimate); `null` when the weekly window is empty. */
+  readonly weeklyResetsAt: string | null;
+  /** ALWAYS `true` — these are estimates from local aggregation, not an official API. */
+  readonly estimated: true;
+}
+
+/**
+ * The `~/.claude/projects` root (the account-wide transcript store). Overridable via
+ * `DZ_CLAUDE_PROJECTS_ROOT` — used by tests to point at a temp tree (and by any user who relocates
+ * the Claude home). Never throws.
+ */
+function claudeProjectsRoot(): string {
+  const override = process.env['DZ_CLAUDE_PROJECTS_ROOT'];
+  if (typeof override === 'string' && override.length > 0) return override;
+  return join(homedir(), '.claude', 'projects');
+}
+
+/**
+ * Read `memory.usage.{sessionTokenLimit,weeklyTokenLimit}` from `<projectRoot>/.dz/config.json`.
+ * NEVER throws — absent/corrupt/partial config ⇒ `{}` (⇒ pct `null`). Mirrors the
+ * `readVectorEngineMode` never-throw shape exactly. `projectRoot` is the ONLY thing that scopes to
+ * a project; the MEASUREMENT below is account-wide (FR-1.6).
+ */
+export function readUsageLimits(projectRoot: string): UsageLimits {
+  try {
+    const cfg = JSON.parse(readFileSync(join(projectRoot, '.dz', 'config.json'), 'utf-8')) as {
+      memory?: { usage?: { sessionTokenLimit?: unknown; weeklyTokenLimit?: unknown } };
+    };
+    const u = cfg.memory?.usage;
+    if (!u || typeof u !== 'object') return {};
+    const out: { sessionTokenLimit?: number; weeklyTokenLimit?: number } = {};
+    const s = u.sessionTokenLimit;
+    const w = u.weeklyTokenLimit;
+    if (typeof s === 'number' && isFinite(s) && s > 0) out.sessionTokenLimit = s;
+    if (typeof w === 'number' && isFinite(w) && w > 0) out.weeklyTokenLimit = w;
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+/** One extracted transcript sample. */
+interface Sample {
+  readonly ts: number; // ms epoch
+  readonly tokens: number;
+  readonly key: string; // dedup key: message.id + ':' + requestId
+}
+
+/**
+ * List every `*.jsonl` under `~/.claude/projects/<dir>/`, best-effort. Never throws — an
+ * unreadable dir/file is skipped. Returns absolute paths + their `mtimeMs` (the prefilter lever).
+ */
+function listTranscriptFiles(root: string): Array<{ path: string; mtimeMs: number }> {
+  const out: Array<{ path: string; mtimeMs: number }> = [];
+  let dirs: string[];
+  try {
+    if (!existsSync(root)) return out;
+    dirs = readdirSync(root);
+  } catch {
+    return out;
+  }
+  for (const d of dirs) {
+    const projDir = join(root, d);
+    let files: string[];
+    try {
+      const st = statSync(projDir);
+      if (!st.isDirectory()) continue;
+      files = readdirSync(projDir);
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (!f.endsWith('.jsonl')) continue;
+      const p = join(projDir, f);
+      try {
+        out.push({ path: p, mtimeMs: statSync(p).mtimeMs });
+      } catch {
+        // skip a file we can't stat
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Extract usage samples from one transcript file. Never throws — a corrupt line is skipped
+ * (statusline discipline). A cheap `"usage"` substring pre-filter avoids `JSON.parse` on lines
+ * that cannot carry a token count. `weeklyCutoff` drops samples older than the rolling window.
+ */
+function extractSamples(path: string, weeklyCutoff: number, into: Sample[], seen: Set<string>): void {
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf-8');
+  } catch {
+    return;
+  }
+  const lines = raw.split('\n');
+  for (const line of lines) {
+    if (line.length === 0) continue;
+    if (line.indexOf('usage') === -1) continue; // cheap pre-filter before the parse
+    let rec: {
+      timestamp?: unknown;
+      requestId?: unknown;
+      message?: {
+        id?: unknown;
+        usage?: {
+          input_tokens?: unknown;
+          cache_creation_input_tokens?: unknown;
+          cache_read_input_tokens?: unknown;
+          output_tokens?: unknown;
+        };
+      };
+    };
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue; // corrupt line — skip, never throw
+    }
+    const usage = rec.message?.usage;
+    if (!usage || typeof usage !== 'object') continue;
+    const tsRaw = rec.timestamp;
+    if (typeof tsRaw !== 'string' && typeof tsRaw !== 'number') continue;
+    const ts = typeof tsRaw === 'number' ? tsRaw : Date.parse(tsRaw);
+    if (!isFinite(ts)) continue;
+    if (ts < weeklyCutoff) continue; // outside the weekly window — cannot contribute
+    const n = (v: unknown): number => (typeof v === 'number' && isFinite(v) && v > 0 ? v : 0);
+    const tokens =
+      n(usage.input_tokens) +
+      n(usage.cache_creation_input_tokens) +
+      n(usage.cache_read_input_tokens) +
+      n(usage.output_tokens);
+    if (tokens <= 0) continue;
+    // Dedup: streamed assistant messages repeat their usage object across chunks.
+    const id = typeof rec.message?.id === 'string' ? rec.message.id : '';
+    const reqId = typeof rec.requestId === 'string' ? rec.requestId : '';
+    const key = id + ':' + reqId;
+    if (id !== '' || reqId !== '') {
+      if (seen.has(key)) continue;
+      seen.add(key);
+    }
+    into.push({ ts, tokens, key });
+  }
+}
+
+/**
+ * Compute the SESSION active-block total using ccusage 5h-block semantics: walk samples in ts
+ * order; a block starts at the first sample after the previous block ends, FLOORED to the hour;
+ * `end = start + 5h`. The ACTIVE block is the one whose `[start, end)` contains `now`. No active
+ * block ⇒ `{ tokens: 0, resetsAt: null }`.
+ */
+function activeBlock(samplesAsc: Sample[], now: number): { tokens: number; resetsAt: string | null } {
+  let blockStart = -1;
+  let blockEnd = -1;
+  let tokens = 0;
+  let activeStart = -1;
+  let activeTokens = 0;
+  for (const s of samplesAsc) {
+    if (blockStart === -1 || s.ts >= blockEnd) {
+      // close the previous block, open a new one floored to the hour
+      blockStart = Math.floor(s.ts / HOUR_MS) * HOUR_MS;
+      blockEnd = blockStart + SESSION_BLOCK_MS;
+      tokens = 0;
+    }
+    tokens += s.tokens;
+    if (now >= blockStart && now < blockEnd) {
+      activeStart = blockStart;
+      activeTokens = tokens;
+    }
+  }
+  if (activeStart === -1) return { tokens: 0, resetsAt: null };
+  return { tokens: activeTokens, resetsAt: new Date(activeStart + SESSION_BLOCK_MS).toISOString() };
+}
+
+/**
+ * Estimate SESSION + WEEKLY token usage from the local Claude transcript store. NEVER throws;
+ * READONLY; `<100ms` steady-state via the `mtime` prefilter. `projectRoot` scopes ONLY the config
+ * (limits) read — measurement is account-wide (all projects). `now` is injectable for tests.
+ */
+export function computeUsage(projectRoot: string, now?: number): UsageEstimate {
+  const nowMs = typeof now === 'number' && isFinite(now) ? now : Date.now();
+  const limits = readUsageLimits(projectRoot);
+  const weeklyCutoff = nowMs - WEEK_MS - MTIME_SLACK_MS;
+
+  const samples: Sample[] = [];
+  const seen = new Set<string>();
+  try {
+    const files = listTranscriptFiles(claudeProjectsRoot());
+    for (const f of files) {
+      // mtime prefilter: a file last written before the weekly cutoff cannot hold in-window
+      // samples — skip it WITHOUT opening it (the <100ms lever).
+      if (f.mtimeMs < weeklyCutoff) continue;
+      extractSamples(f.path, weeklyCutoff, samples, seen);
+    }
+  } catch {
+    // total scan failure ⇒ fall through with empty samples (nulls), never throw
+  }
+
+  // Weekly total: every sample inside the exact 7d window (the +slack was only a prefilter guard).
+  const weeklyHardCutoff = nowMs - WEEK_MS;
+  let weeklyTokens = 0;
+  let oldestInWindow = -1;
+  for (const s of samples) {
+    if (s.ts < weeklyHardCutoff) continue;
+    weeklyTokens += s.tokens;
+    if (oldestInWindow === -1 || s.ts < oldestInWindow) oldestInWindow = s.ts;
+  }
+
+  const asc = samples.slice().sort((a, b) => a.ts - b.ts);
+  const block = activeBlock(asc, nowMs);
+
+  const pct = (tokens: number, limit?: number): number | null =>
+    typeof limit === 'number' && limit > 0 ? Math.round((100 * tokens) / limit) : null;
+
+  const weeklyResetsAt = oldestInWindow === -1 ? null : new Date(oldestInWindow + WEEK_MS).toISOString();
+
+  return {
+    sessionTokens: block.tokens,
+    weeklyTokens,
+    sessionPct: pct(block.tokens, limits.sessionTokenLimit),
+    weeklyPct: pct(weeklyTokens, limits.weeklyTokenLimit),
+    sessionResetsAt: block.resetsAt,
+    weeklyResetsAt,
+    estimated: true,
+  };
+}

package/src/vector-tier.ts

@@ -47,8 +47,11 @@ import {
   patternIdentityOf,
   dreamRecordId,
   loadStoreRecords,
+  readMemoryLearningConfig,
+  readReinforcementState,
   removePatternsByIds,
   snapshotStore,
+  updateReinforcementState,
   type PatternRecord,
   type RecallHit,
 } from './patterns.js';
@@ -62,6 +65,7 @@ import {
   reindexAgentdbRows,
 } from './agentdb-index.js';
 import { currentEmbedManifest, guardEmbedSpace, DEFAULT_EMBED_DIM, resolveEmbedModel, type EmbedModelConfig } from './embedding-config.js';
+import { applyLearningSignals, resolveLearningBackend, type LearningSignalBackend } from './learning-backend.js';
 
 /* ------------------------------------------------------------------ */
 /*  Types (04_domain_model §3.4 / §4.1)                                */
@@ -85,6 +89,8 @@ export interface VectorEntry {
   readonly taskType: string;
   readonly tags?: readonly string[] | undefined;
   readonly metadata?: Record<string, unknown> | undefined;
+  readonly uses?: number | undefined;
+  readonly avgReward?: number | undefined;
 }
 
 /** One semantic search hit — a POINTER into the lexical store, never a pattern by itself. */
@@ -179,6 +185,7 @@ export const DEFAULT_VECTOR_TIMEOUT_MS = 10_000;
 
 /** Default cosine cutoff for near-duplicate clustering (`--threshold` / config overrides). */
 export const DEFAULT_HARMONIZE_THRESHOLD = 0.92;
+export const REINFORCE_RRF_CAP = (1 / (60 + 1)) - (1 / (60 + 4));
 
 /* ------------------------------------------------------------------ */
 /*  Harmonize + import types (dz-vector-harmonize-import 05 §2.1/§2.2)  */
@@ -262,6 +269,10 @@ export interface ReindexVectorReport {
   readonly error?: string;
 }
 
+export type TeachGuardResult =
+  | { readonly action: 'teach'; readonly reason?: string }
+  | { readonly action: 'reinforce'; readonly dzId: string; readonly cosine: number };
+
 /* ------------------------------------------------------------------ */
 /*  Timeout wrapper (both legs — NC1/QR-1)                             */
 /* ------------------------------------------------------------------ */
@@ -351,6 +362,7 @@ export function dreamVectorEntry(d: DreamPattern): VectorEntry | undefined {
 /** ACL: stored {@link MemoryRecord} → {@link VectorEntry} (the consolidate-backfill mapper). */
 export function memoryRecordVectorEntry(r: MemoryRecord): VectorEntry | undefined {
   if (isVectorNoise(r.text)) return undefined;
+  const state = readReinforcementState(r);
   return {
     dzId: r.id,
     text: r.text,
@@ -358,6 +370,8 @@ export function memoryRecordVectorEntry(r: MemoryRecord): VectorEntry | undefine
     taskType: r.id.startsWith('dream:') ? 'dz-learning' : 'dz-teach',
     tags: ['dz-backfill', r.outcome],
     metadata: { dzId: r.id, source: r.metadata?.['source'] ?? 'dz-backfill', ts: r.timestamp, skillId: r.skillId },
+    uses: state.uses,
+    avgReward: state.avgReward,
   };
 }
 
@@ -726,6 +740,14 @@ export function mergeHybridHits(
     }));
 }
 
+function markRecallHits(projectRoot: string, backend: LearningSignalBackend, hits: readonly HybridHit[], idOf: (p: PatternRecord) => string): void {
+  const cfg = readMemoryLearningConfig(projectRoot);
+  if (cfg.backend === 'off' || cfg.onRecallHits === false) return;
+  const ts = new Date().toISOString();
+  for (const h of hits) backend.addSample({ dzId: idOf(h.pattern), kind: 'recall-hit', reward: h.pattern.reward, ts });
+  void backend.train().catch(() => undefined);
+}
+
 /**
  * Hybrid recall (FR-3): lexical `recallPatterns` FIRST (always, sync, UNCHANGED — AC-5), then a
  * time-bounded semantic leg merged via RRF. Degradation contract (I-1): with no engine — or on
@@ -749,23 +771,50 @@ export async function recallHybrid(
   const mode = opts.mode ?? 'hybrid';
   const lexical = recallPatterns(projectRoot, query, limit);
   const lexicalBackend: 'sqlite' | 'json' = lexical[0]?.backend === 'sqlite' ? 'sqlite' : 'json';
+  const records = loadStoreRecords(projectRoot);
+  const idToRecord = new Map<string, MemoryRecord>();
+  const identityToId = new Map<string, string>();
+  for (const r of records) {
+    idToRecord.set(r.id, r);
+    identityToId.set(patternIdentityOf(recordToPattern(r)), r.id);
+  }
+  const idOf = (p: PatternRecord): string => identityToId.get(patternIdentityOf(p)) ?? patternRecordId(p);
+  const learning = resolveLearningBackend(projectRoot);
+  const enhance = (hits: readonly HybridHit[]): HybridHit[] => applyLearningSignals(
+    hits,
+    learning,
+    hits.map((h) => {
+      const dzId = idOf(h.pattern);
+      const rec = idToRecord.get(dzId);
+      return { dzId, score: h.score, reinforcement: rec !== undefined ? readReinforcementState(rec) : undefined };
+    }),
+    REINFORCE_RRF_CAP,
+  );
   const lexicalOnly = (extra: Partial<Pick<HybridRecall, 'vectorEngine' | 'vectorReason' | 'vectorError'>>): HybridRecall => ({
-    hits: lexical.map((h, rank) => ({ pattern: h.pattern, backend: h.backend, score: 1 / (RRF_K + rank + 1) })),
+    hits: enhance(lexical.map((h, rank) => ({ pattern: h.pattern, backend: h.backend, score: 1 / (RRF_K + rank + 1) }))),
     lexicalBackend,
     vectorEngine: 'none',
     ...extra,
   });
 
-  if (mode === 'lexical') return lexicalOnly({});
+  if (mode === 'lexical') {
+    const out = lexicalOnly({});
+    markRecallHits(projectRoot, learning, out.hits, idOf);
+    return out;
+  }
 
   let resolved: ResolvedVectorEngine;
   try {
     resolved = pickEngine(projectRoot, opts);
   } catch (err) {
-    return lexicalOnly({ vectorReason: err instanceof Error ? err.message : String(err) });
+    const out = lexicalOnly({ vectorReason: err instanceof Error ? err.message : String(err) });
+    markRecallHits(projectRoot, learning, out.hits, idOf);
+    return out;
   }
   if (resolved.engine === undefined) {
-    return lexicalOnly(resolved.reason !== undefined ? { vectorReason: resolved.reason } : {});
+    const out = lexicalOnly(resolved.reason !== undefined ? { vectorReason: resolved.reason } : {});
+    markRecallHits(projectRoot, learning, out.hits, idOf);
+    return out;
   }
   const engine = resolved.engine;
   const timeoutMs = opts.timeoutMs ?? DEFAULT_VECTOR_TIMEOUT_MS;
@@ -779,22 +828,16 @@ export async function recallHybrid(
     () => ({ hits: [] as VectorHit[], error: `vector search timed out after ${timeoutMs}ms` }),
   );
   if (sr.error !== undefined) {
-    return { ...lexicalOnly({}), vectorEngine: engine.kind, vectorError: sr.error };
+    const out = { ...lexicalOnly({}), vectorEngine: engine.kind, vectorError: sr.error };
+    markRecallHits(projectRoot, learning, out.hits, idOf);
+    return out;
   }
 
   // Resolve dzId → the FULL lexical record (source of truth). Orphans are dropped (V-1/QR-4).
-  let records: MemoryRecord[];
-  try {
-    records = loadStoreRecords(projectRoot);
-  } catch {
-    records = [];
-  }
   const idToPattern = new Map<string, PatternRecord>();
-  const identityToId = new Map<string, string>();
   for (const r of records) {
     const p = recordToPattern(r);
     idToPattern.set(r.id, p);
-    identityToId.set(patternIdentityOf(p), r.id);
   }
   const semantic: RankedPattern[] = [];
   const seen = new Set<string>();
@@ -810,10 +853,34 @@ export async function recallHybrid(
     pattern: h.pattern,
     backend: h.backend,
   }));
-  const hits = mergeHybridHits(lex, semantic, { limit, semanticWeight: mode === 'semantic' ? 2 : 1 });
+  const hits = enhance(mergeHybridHits(lex, semantic, { limit, semanticWeight: mode === 'semantic' ? 2 : 1 }));
+  markRecallHits(projectRoot, learning, hits, idOf);
   return { hits, lexicalBackend, vectorEngine: engine.kind };
 }
 
+export async function teachGuard(
+  projectRoot: string,
+  text: string,
+  opts: VectorServiceOptions & { readonly reward?: number | undefined; readonly threshold?: number | undefined } = {},
+): Promise<TeachGuardResult> {
+  const cfg = readMemoryLearningConfig(projectRoot);
+  const threshold = Math.max(0.95, opts.threshold ?? cfg.reinforceThreshold);
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_VECTOR_TIMEOUT_MS;
+  const result = await withVectorTimeout(
+    searchAgentdbPatterns(projectRoot, text, { limit: 1 }),
+    timeoutMs,
+    () => ({ hits: [], error: `teach guard timed out after ${timeoutMs}ms` }),
+  );
+  if (result.error !== undefined) return { action: 'teach', reason: result.error };
+  const hit = result.hits[0];
+  if (hit === undefined || hit.dzId === undefined || hit.similarity < threshold) return { action: 'teach' };
+  const rec = loadStoreRecords(projectRoot).find((r) => r.id === hit.dzId);
+  if (opts.reward !== undefined && rec !== undefined && Math.abs(rec.score - opts.reward) > 0.000001) {
+    return { action: 'teach', reason: 'reward differs; preserving corrected-reward fork' };
+  }
+  return { action: 'reinforce', dzId: hit.dzId, cosine: hit.similarity };
+}
+
 /* ------------------------------------------------------------------ */
 /*  Status (dz vector status / dz doctor divergence line)              */
 /* ------------------------------------------------------------------ */
@@ -963,8 +1030,15 @@ function buildCluster(
   const members = indices.map((i) => items[i]!);
   const keeperIdx = indices[selectClusterKeeper(members)]!;
   const keeper = items[keeperIdx]!;
+  // FORK-PRESERVATION CARVE-OUT (the ADR's #1 safety property — distinct-lesson-never-lost): a
+  // SAME-TEXT member whose reward differs from the keeper's is a fork-on-corrected-reward
+  // (patterns.ts:279-284 intent) — the CORRECTION must survive even when it is a DOWNGRADE
+  // (keeper = max reward would otherwise delete it). Mirrors teachGuard's reward-diff ε. Scoped to
+  // SAME TEXT only: semantically-similar-but-differently-worded near-dups still merge normally
+  // (that IS harmonize's job; the keeper keeps max reward + provenance).
   const drops = indices
     .filter((i) => i !== keeperIdx)
+    .filter((i) => !(items[i]!.text === keeper.text && Math.abs(items[i]!.reward - keeper.reward) > 0.000001))
     .map((i) => ({ dzId: items[i]!.dzId, text: items[i]!.text, reward: items[i]!.reward, cos: cosToKeeper(i, keeperIdx) }));
   return { keep: { dzId: keeper.dzId, text: keeper.text, reward: keeper.reward, ts: keeper.ts }, drops };
 }
@@ -981,7 +1055,8 @@ function semanticClusters(items: readonly HarmonizeItem[], vecs: readonly Float3
   const clusters: HarmonizeCluster[] = [];
   for (const comp of connectedComponents(n, edges)) {
     if (comp.length < 2) continue;
-    clusters.push(buildCluster(items, comp, (d, k) => cosineSimilarity(vecs[d]!, vecs[k]!)));
+    const c = buildCluster(items, comp, (d, k) => cosineSimilarity(vecs[d]!, vecs[k]!));
+    if (c.drops.length > 0) clusters.push(c); // all members carved out as reward-forks ⇒ no-op cluster
   }
   return clusters;
 }
@@ -997,7 +1072,8 @@ function exactClusters(items: readonly HarmonizeItem[]): HarmonizeCluster[] {
   const clusters: HarmonizeCluster[] = [];
   for (const indices of byText.values()) {
     if (indices.length < 2) continue;
-    clusters.push(buildCluster(items, indices, () => 1.0));
+    const c = buildCluster(items, indices, () => 1.0);
+    if (c.drops.length > 0) clusters.push(c); // same-text reward-forks are preserved, not merged
   }
   return clusters;
 }
@@ -1124,6 +1200,28 @@ export async function harmonizeVectorStore(projectRoot: string, opts: HarmonizeO
     // Backup write failed ⇒ ABORT the drop (no partial mutation — the store is untouched).
     return { ...base, error: `backup failed — drop aborted: ${snap.error}` };
   }
+  for (const c of clusters) {
+    const keepRec = records.find((r) => r.id === c.keep.dzId);
+    if (keepRec === undefined) continue;
+    const keepState = readReinforcementState(keepRec);
+    let uses = keepState.uses + c.drops.length;
+    const rewards = [c.keep.reward];
+    const mergedFrom = [...keepState.mergedFrom];
+    for (const d of c.drops) {
+      const rec = records.find((r) => r.id === d.dzId);
+      const st = rec !== undefined ? readReinforcementState(rec) : undefined;
+      uses += st?.uses ?? 0;
+      rewards.push(d.reward);
+      if (st !== undefined) mergedFrom.push(...st.mergedFrom);
+      mergedFrom.push(d.dzId);
+    }
+    await updateReinforcementState(projectRoot, c.keep.dzId, {
+      uses,
+      lastUsedTs: new Date().toISOString(),
+      avgReward: rewards.reduce((a, b) => a + b, 0) / rewards.length,
+      mergedFrom,
+    });
+  }
   const removal = removePatternsByIds(projectRoot, dropDzIds);
   logHarmonizeNote(projectRoot, { dropped: removal.removed, kept, engine: engineKind, error: removal.error });
   return { ...base, backupPath, ...(removal.error !== undefined ? { error: removal.error } : {}) };
@@ -1264,6 +1362,8 @@ function agentdbVectorEngine(projectRoot: string): VectorEngine {
           score: e.score,
           ...(e.tags !== undefined ? { tags: e.tags } : {}),
           ...(e.metadata !== undefined ? { metadata: e.metadata } : {}),
+          ...(e.uses !== undefined ? { uses: e.uses } : {}),
+          ...(e.avgReward !== undefined ? { avgReward: e.avgReward } : {}),
         })),
       );
       return { indexed: r.indexed, ...(r.error !== undefined ? { error: r.error } : {}) };