@dzhechkov/harness-cli 0.3.195 → 0.3.198

package/README.md

@@ -356,27 +356,29 @@ Get the whole set with `dz init --target claude-code --preset meta`, or pick one
 
 > **A skill and its npx toolkit are not duplicates — they're a graduation.** Several skills (e.g. `feature-adr`, `design-thinking`) exist BOTH as a skill inside a `dz` preset AND as a standalone `npx` package. The preset's SKILL.md is **fully functional on its own** (the whole methodology — modules + references — travels with it, and it auto-activates by description), and it's the only way to compile that capability to the **non-Claude platforms** (Codex/OpenCode/Hermes/OpenClaude) via `dz`. The npx package adds **project-level runtime governance** around the same skill: a slash command, governance rules, a context shard, and (for feature-adr) reward-learning + `/harvest`. So: pick the **skill/preset** for a working capability across platforms; pick the **npx toolkit** when you want it as a governed, command-driven fixture of one project.
 
-## All Commands (39)
+## All Commands (40)
 
 ```
 dz setup             --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--install-driver] [--force]
 dz init              --target <name> [--preset <name>] [--select id,id,...] [--force]
 dz install           <npm-pkg> [--target <name>] [--project <dir>] [--force]
 dz bundle            [--preset <name> | --select id,...] [--out <dir>] [--skills-dir <dir>] [--force]
-dz teach             "<pattern>" [--reward <0-1>] [--domain <name>] [--type rule|success-pattern|lesson-learned] [--project <dir>] [--no-mirror]   # --project pins the learned store to <dir>/.dz (not the cwd) — pin to a canonical brain
-dz teach --from-json <file> [--project <dir>] [--no-mirror]   # bulk-import a `dz recall --all --json` export (share a learned store across machines)
+dz teach             "<pattern>" [--reward <0-1>] [--domain <name>] [--type rule|success-pattern|lesson-learned] [--project <dir>] [--no-mirror] [--guard]   # --project pins the learned store to <dir>/.dz (not the cwd) — pin to a canonical brain
+dz teach --reinforce "<dzId-or-exact-text>" [--project <dir>] # bump an existing learned pattern instead of writing a near-duplicate
+dz teach --from-json <file> [--project <dir>] [--no-mirror] [--harmonize]   # bulk-import a `dz recall --all --json` export; prints a harmonize dry-run advisory
 dz consolidate       [--sessions-dir <dir>] [--project <dir>] [--no-mirror]
 dz recall            "<query>" [--limit <N>] [--semantic | --no-semantic] [--project <dir>]   # hybrid lexical+vector when the vector tier is enabled
-dz recall --all      [--json]                       # export the WHOLE learned store (portable SHARING form — the input for `dz teach --from-json`)
+dz recall --all      [--json] [--stats]             # export the WHOLE learned store, or inspect learning stats/top uses
 dz recall --books    "<query>" [--book <slug>]      # digitized-book KUs; --book narrows to one book
 dz vector status     [--project <dir>] [--json]     # semantic tier: engine availability, mirrored vs lexical counts, pending queue
 dz vector export     <path> [--project <dir>]       # portable VECTOR form (.rvf checkpoint; needs the opt-in RVF engine)
 dz vector import     <file.rvf> [--project <dir>] [--json]         # RVF import — UPSERT-BY-dzId (idempotent, never overwrites; orphans skipped)
-dz vector harmonize  [--apply] [--threshold <0..1>] [--json]       # SEMANTIC dedup of the learned store (dry-run default; --apply after a restorable backup)
+dz vector harmonize  [--apply] [--threshold <0..1>] [--json]       # SEMANTIC merge of near-dups (dry-run default; --apply after a restorable backup)
 dz teach --harmonize [--apply] [--threshold <0..1>]                # alias of `dz vector harmonize`
 dz statusline        [--json] [--install]   # compact Claude Code statusline: live self-learning pattern count + brain sources
+dz usage             [--json] [--project <dir>]   # ESTIMATE Claude session (5h-block) + weekly (7d) token usage from local transcripts; exit 0 ALWAYS; pct=null when limits unconfigured
 dz brain list        [--json]                                        # the durable cross-project knowledge brain
-dz brain query       "<q>" [--source <slug>] [--limit <N>] [--any] [--rerank] [--json]  # cross-source recall (--any = OR match; --rerank reorders on-point first)
+dz brain query       "<q>" [--source <slug>] [--limit <N>] [--any] [--rerank] [--json]  # cross-source recall (--any = OR match; --rerank reorders on-point first). Auto-broadens: if strict all-terms match yields 0 hits, it retries once as OR and labels the result "broadened" (text note + broadened:true in --json) instead of returning empty. Explicit --any is OR from the start (never labeled broadened).
 dz brain add         [--source <slug>] [--project <dir>] [--from-slice <f>|--from-pack <p>|--from-kus <f> --slug <s> --kind <k> --license <spdx> [--override]] [--json]  # grow the brain
 dz brain ground      "<prompt>" [--k <N>] [--source <slug>] [--text] [--budget <N>] [--full]  # retrieve + emit grounding citations (hook entrypoint; silent if irrelevant); --budget N eager-inlines top-K KU content within ~N tokens (chars/4 approx); --full = --budget 8000
 dz brain expand      <kuId> [--source <slug>] [--json]               # full-content lookup by kuId — the command the grounding directive names; prints name/problem/pages/book + FULL content (untruncated)
@@ -463,6 +465,32 @@ distills new learnings. It's **opt-in** and **non-clobbering**: `--install` merg
 existing `statusLine` config rather than overwriting it, and nothing changes until you run it.
 Modeled on the Agentic QE statusline pattern (e.g. AQE's `🎓 12 patterns`).
 
+### Usage estimate (`dz usage`)
+
+`dz usage` prints a READONLY, never-throw ESTIMATE of Claude SESSION (active 5h-block) and WEEKLY
+(rolling 7d) token usage, aggregated from your local `~/.claude/projects/**/*.jsonl` transcripts:
+
+```bash
+dz usage           # session ~74% (resets 19:00) · week ~52% (resets Sat) · estimated
+dz usage --json    # {"sessionPct":74,"weeklyPct":52,"sessionTokens":…,"resetsAt":{…},"limits":{…},"estimated":true}
+```
+
+**Exit code is 0 ALWAYS** (even unconfigured/error → all-null JSON) — a probe must never distinguish
+"usage unknown" from "command failed" via a non-zero exit. Percentages are **ESTIMATES** (there is no
+official usage API); they are `null` until you configure the plan-dependent limits in `.dz/config.json`:
+
+```json
+{ "memory": { "usage": { "sessionTokenLimit": 200000000, "weeklyTokenLimit": 1000000000 } } }
+```
+
+Both keys are OPTIONAL — absent ⇒ that `pct` is `null` (unknown, never `0`). **Calibrate** by scaling a
+limit by `X/100` when a real limit-hit lands at an estimated `X%` (observed-exhaustion calibration).
+This feeds `/feature-adr`'s **usage-adaptive routing** — the pipeline probes `dz usage --json` at each
+phase boundary and pre-emptively routes the remaining stages to Codex when usage crosses the threshold
+(default 70%). **Honest caveat:** at TRUE exhaustion even the Codex dispatch dies (`codex:codex-rescue`
+is a Claude wrapper), so the switch must happen BEFORE — the pre-emptive probe, not reactive detection,
+is the real defense.
+
 ### Targets (10 platforms — 5 lossless + Copilot + AGENTS.md + Cursor + Gemini + Windsurf)
 
 Five platforms natively support the [agentskills.io](https://agentskills.io) `SKILL.md` format:
@@ -1114,7 +1142,9 @@ The learned store round-trips across machines in **two** formats, and de-duplica
 
 **Does `dz vector import` overwrite my store? NO.** Import is **upsert-by-dzId** (our vectors are keyed by the content-addressed `dzId`), so re-importing the *same* `.rvf` twice adds **zero** duplicates and **deletes nothing** — it only inserts new dzIds and replaces the embedding of dzIds it already knows. A dzId with no local pattern is an **orphan**: skipped + counted, with a hint to import the *text* first (`dz teach --from-json`), because embeddings are model-locked but text is not. (Grounded in RuVector's own upsert-by-id merge model — see [rUv RVF](https://github.com/ruvnet/ruvector); the shipped `@ruvector/rvf` SDK exposes no vector read-out, so import reads the `.rvf.idmap.json` dzId sidecar and re-embeds the local text under a **manifest guard** that refuses a foreign model/dim.)
 
-**`dz vector harmonize` — semantic dedup.** `dz teach --from-json` only dedups by *exact* text, so paraphrases survive: *"use DataLoader to batch queries"* and *"batch DB round-trips with a dataloader"* are two rows forever. Harmonize finds near-duplicate **clusters** by cosine similarity (θ default `0.92`, `--threshold`), keeps the **highest-reward** member of each (tie-break: longer/more-specific text, then newer `ts`), and drops the rest — **dry-run by default** (previews, writes nothing), reversible on `--apply` (writes a restorable backup first). It **never** drops a unique (non-duplicated) pattern. With no vector engine it degrades to **exact-text dedup + an honest note** — never throws.
+**`dz vector harmonize` — semantic merge.** `dz teach --from-json` only dedups by *exact* text, so paraphrases survive: *"use DataLoader to batch queries"* and *"batch DB round-trips with a dataloader"* are separate rows. Harmonize finds near-duplicate **clusters** by cosine similarity (θ default `0.92`, `--threshold`), keeps the **highest-reward** member of each (tie-break: longer/more-specific text, then newer `ts`), folds reinforcement signal into the keeper (`uses = Σ member uses + drops`, `avgReward` = honest mean of observed member rewards, `mergedFrom` = dropped ids), then removes the rest only on `--apply`. Dry-run previews and writes nothing; apply writes a restorable backup first. It **never** drops a unique pattern. With no vector engine it degrades to **exact-text dedup + an honest note** — never throws.
+
+**Learning signal seam.** Ranking reinforcement is behind `memory.learning.backend`: default `native` (bounded uses/recency/reward signal), kill switch `off`, and reserved `ruvector-gnn` (accepted by config with an honest fallback to native; no RuVector dependency is installed). `memory.learning.onRecallHits:false` disables the default recall-hit auto-bump. `dz teach --reinforce "<id-or-text>"` records an explicit use; `dz teach --guard` is opt-in and only reinforces near-duplicates at θ ≥ `0.95`, while a different reward still writes a new record. `dz recall --all --stats` shows store size, domains, top uses, duplicate groups, and re-teach/reinforce trend counters.
 
 **Before → after** (one near-dup cluster):
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmJH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAykGD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8G5E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyJH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAitGD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgH5E"}

package/dist/cli.js

@@ -9,7 +9,7 @@ import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
-import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, WORKFLOW_NAMES, importEcc, recordPattern, consolidateSessions, pruneNoisePatterns, recallHybrid, mirrorPatternsToVector, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, queryBookKnowledge, loadStorePatternsSync, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, } from '@dzhechkov/harness-core';
+import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, recallHybrid, teachGuard, mirrorPatternsToVector, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, readUsageLimits, queryBookKnowledge, loadStorePatternsSync, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 const USAGE = `dz - DZ cross-platform harness CLI
@@ -51,6 +51,7 @@ Usage:
   dz brain init  [--project <dir>] [--k <N>]                           (wire the grounding hook into .claude/settings.json — opt-in)
   dz statusline [--json] [--install] [--project <dir>]                 (live self-learning panel for Claude Code's status bar; reads the CC JSON payload from STDIN)
   dz statusline --fa-record --slug <s> --step "<label>" [--recalled <n>] [--stored <n>] [--mode <m>]   (feature-adr: record live per-run learning state → 📐 panel segment)
+  dz usage [--json] [--project <dir>]                                  (ESTIMATE Claude session (5h-block) + weekly (7d) token usage from local transcripts; exit 0 ALWAYS; pct=null when memory.usage.{sessionTokenLimit,weeklyTokenLimit} unconfigured in .dz/config.json)
   dz pretrain [--project <dir>]
   dz recommend "<task description>"
   dz compose <preset1+preset2+...> [--target <name>]
@@ -886,17 +887,21 @@ function cmdStatuslineFaRecord(options, cwd, write) {
     const stored = parseCount('stored');
     if (stored === undefined)
         return 1;
+    const reinforced = parseCount('reinforced');
+    if (reinforced === undefined)
+        return 1;
     const mode = options.get('mode');
     const projectRoot = resolve(cwd, options.get('project') ?? '.');
     const state = writeFeatureAdrState(projectRoot, {
         slug, step, recalled, stored,
+        ...(reinforced > 0 ? { reinforced } : {}),
         ...(mode !== undefined && mode.trim() !== '' ? { mode: mode.trim() } : {}),
     });
     if (state === undefined) {
         write(`dz statusline --fa-record: could not write learning state under ${projectRoot}/.dz/feature-adr/`);
         return 1;
     }
-    write(`dz statusline: recorded /feature-adr learning state for "${slug}" (${step}) — 🎓 ${state.pool} pool · ↑${state.recalled} used · +${state.stored} new`);
+    write(`dz statusline: recorded /feature-adr learning state for "${slug}" (${step}) — 🎓 ${state.pool} pool · ↑${state.recalled} used · +${state.stored} new · ↻${state.reinforced ?? 0} reinforced`);
     return 0;
 }
 /**
@@ -931,7 +936,7 @@ function cmdStatusline(options, flags, cwd, write, readStdin) {
         // Live /feature-adr run in flight → PREPEND the pipeline learning segment to the base dz line.
         const fa = data.featureAdr;
         if (fa !== undefined) {
-            line = `📐 feature-adr ${fa.step} · 🎓 ${fa.pool} pool · ↑${fa.recalled} used · +${fa.stored} new · ${line}`;
+            line = `📐 feature-adr ${fa.step} · 🎓 ${fa.pool} pool · ↑${fa.recalled} used · +${fa.stored} new · ↻${fa.reinforced ?? 0} reinforced · ${line}`;
         }
         write(line);
         return 0;
@@ -942,6 +947,72 @@ function cmdStatusline(options, flags, cwd, write, readStdin) {
         return 0;
     }
 }
+/**
+ * `dz usage` — print an ESTIMATE of Claude session (active 5h-block) + weekly (rolling 7d) token
+ * usage, aggregated READONLY from the local transcript store (see {@link computeUsage}). `--json`
+ * emits the single-line contract the feature-adr usage-probe agent parses; the human path prints a
+ * compact `session ~74% (resets 19:00) · week ~52% (resets Sat)` or an unconfigured hint.
+ *
+ * **Exit code is 0 ALWAYS** — including on internal error the whole body is guarded and prints the
+ * all-null JSON, so a probe can NEVER distinguish "usage unknown" from "command failed" via a
+ * non-zero exit (unknown is a first-class value, INV-3). `--project <dir>` scopes ONLY the
+ * `.dz/config.json` limits read; the measurement is account-wide (all projects, FR-1.6).
+ */
+function cmdUsage(options, flags, cwd, write) {
+    const projectRoot = resolve(cwd, options.get('project') ?? '.');
+    const nullContract = () => JSON.stringify({
+        sessionPct: null,
+        weeklyPct: null,
+        sessionTokens: 0,
+        weeklyTokens: 0,
+        resetsAt: { session: null, weekly: null },
+        limits: { session: null, weekly: null },
+        estimated: true,
+    });
+    try {
+        const u = computeUsage(projectRoot);
+        const lim = readUsageLimits(projectRoot);
+        if (flags.has('json')) {
+            write(JSON.stringify({
+                sessionPct: u.sessionPct,
+                weeklyPct: u.weeklyPct,
+                sessionTokens: u.sessionTokens,
+                weeklyTokens: u.weeklyTokens,
+                resetsAt: { session: u.sessionResetsAt, weekly: u.weeklyResetsAt },
+                limits: { session: lim.sessionTokenLimit ?? null, weekly: lim.weeklyTokenLimit ?? null },
+                estimated: true,
+            }));
+            return 0;
+        }
+        if (u.sessionPct === null && u.weeklyPct === null) {
+            write('usage: unconfigured — set memory.usage.sessionTokenLimit / weeklyTokenLimit in .dz/config.json (percentages are ESTIMATES calibrated from observed exhaustion)');
+            return 0;
+        }
+        // Compact human line — a short HH:MM / weekday hint on the resets, best-effort.
+        const clock = (iso) => {
+            if (!iso)
+                return '?';
+            try {
+                return new Date(iso).toISOString().slice(11, 16);
+            }
+            catch {
+                return '?';
+            }
+        };
+        const s = u.sessionPct === null ? 'n/a' : '~' + u.sessionPct + '%';
+        const w = u.weeklyPct === null ? 'n/a' : '~' + u.weeklyPct + '%';
+        write('usage: session ' + s + ' (resets ' + clock(u.sessionResetsAt) + ') · week ' + w + ' (resets ' + clock(u.weeklyResetsAt) + ') · estimated');
+        return 0;
+    }
+    catch {
+        // never let a probe see a non-zero exit — print the all-null contract and exit 0.
+        if (flags.has('json'))
+            write(nullContract());
+        else
+            write('usage: unconfigured — set memory.usage.sessionTokenLimit / weeklyTokenLimit in .dz/config.json');
+        return 0;
+    }
+}
 async function cmdTeach(options, flags, cwd, write) {
     const projectRoot = options.get('project') ?? cwd;
     // Vector tier (dz-rvf-vector-bridge FR-1): best-effort mirror AFTER the lexical write is
@@ -1016,8 +1087,35 @@ async function cmdTeach(options, flags, cwd, write) {
         write(`  Backend: memory (@dzhechkov/memory)  Total now: ${loadStorePatternsSync(projectRoot).length}`);
         // ONE batched mirror call through the same seam as single-teach (QR-6 — no bespoke path).
         await emitMirror(projectRoot, importedRecs, 'dz-teach-import');
+        if (imported > 0) {
+            const report = await harmonizeVectorStore(projectRoot, {});
+            write(`  ℹ ${imported} imported — ${report.clusters.length} near-duplicate cluster(s): review with dz vector harmonize (dry-run); merge with dz vector harmonize --apply after backup`);
+        }
         return 0;
     }
+    const reinforce = options.get('reinforce');
+    if (reinforce !== undefined && reinforce.trim() !== '') {
+        const backend = resolveLearningBackend(projectRoot);
+        const sampleReward = options.has('reward') ? parseFloat(options.get('reward') ?? '0.8') : undefined;
+        backend.addSample({
+            dzId: reinforce,
+            kind: 'reinforce',
+            ts: new Date().toISOString(),
+            ...(sampleReward !== undefined ? { reward: sampleReward } : {}),
+        });
+        const trained = await backend.train();
+        if (trained.flushed > 0) {
+            write(`↳ reinforced ${reinforce}`);
+            return 0;
+        }
+        // HIGH-fix: a no-match must NOT auto-teach the raw argument — callers pass dzIds or truncated
+        // text, so auto-teach minted garbage lessons (observed live). Fail with an honest advisory:
+        // if the lesson is genuinely new, the caller teaches it EXPLICITLY with the full text.
+        write(`dz teach --reinforce: no existing pattern matched ${JSON.stringify(reinforce)} — nothing reinforced`);
+        write('  If this is a genuinely NEW lesson, teach it explicitly:  dz teach "<full lesson text>" --reward <0-1> --domain <area>');
+        write('  To find the exact pattern to reinforce:  dz recall "<terms>"  (match by its full text)');
+        return 1;
+    }
     const pattern = options.get('_positional_0');
     if (!pattern) {
         write('dz teach: pattern description required');
@@ -1028,6 +1126,22 @@ async function cmdTeach(options, flags, cwd, write) {
     }
     const reward = parseFloat(options.get('reward') ?? '0.8');
     const domain = options.get('domain') ?? 'general';
+    if (flags.has('guard')) {
+        const verdict = await teachGuard(projectRoot, pattern, { reward: Math.max(0, Math.min(1, reward)) });
+        if (verdict.action === 'reinforce') {
+            const backend = resolveLearningBackend(projectRoot);
+            backend.addSample({ dzId: verdict.dzId, kind: 'reinforce', reward: Math.max(0, Math.min(1, reward)), ts: new Date().toISOString() });
+            const trained = await backend.train();
+            // HIGH-fix: only claim success when the reinforce actually FLUSHED. With backend 'off'
+            // (NoopLearningBackend) or a flush failure, flushed === 0 — falling through to the plain
+            // teach below so the lesson is NEVER silently discarded (the exact silent-drop the ADR forbids).
+            if (trained.flushed > 0) {
+                write(`↳ reinforced existing pattern ${verdict.dzId} (cos=${verdict.cosine.toFixed(2)}) — not re-added`);
+                return 0;
+            }
+            write(`dz teach --guard: reinforce of ${verdict.dzId} did not flush (backend off or write failure) — teaching the lesson normally instead`);
+        }
+    }
     // Distill pattern into actionable rule (claude-smart inspired)
     // Convert "what happened" into "what to do next time"
     const isRule = pattern.toLowerCase().startsWith('always') || pattern.toLowerCase().startsWith('never') ||
@@ -1131,6 +1245,24 @@ async function cmdRecall(options, flags, cwd, write) {
     // With --json this is the portable export the agentdb-memory MCP bridge consumes.
     if (all) {
         const patterns = loadStorePatternsSync(projectRoot);
+        if (flags.has('stats')) {
+            const stats = storeStats(projectRoot);
+            const backendStats = resolveLearningBackend(projectRoot).getStats();
+            if (asJson) {
+                write(JSON.stringify({ patterns, stats, learning: backendStats }));
+                return 0;
+            }
+            write(`dz recall --all --stats  —  ${patterns.length} learned pattern(s)`);
+            write(`  backend: ${backendStats.backend}${backendStats.advisory !== undefined ? ` (${backendStats.advisory})` : ''}`);
+            write(`  domains: ${Object.entries(stats.perDomain).map(([k, v]) => `${k}=${v}`).join(', ') || 'none'}`);
+            write(`  exact-dup groups: ${stats.exactDupGroups}`);
+            write(`  re-teach trend: ${stats.teachEvents} teach event(s), ${stats.reinforceEvents} reinforce event(s)`);
+            write('  top uses:');
+            for (const row of stats.topUses)
+                write(`    ${row.uses}× [${row.reward.toFixed(2)}] (${row.domain}) ${row.pattern.slice(0, 80)}`);
+            write('  near-dup density: run dz vector harmonize (dry-run)');
+            return 0;
+        }
         if (asJson) {
             write(JSON.stringify(patterns));
         }
@@ -1594,12 +1726,11 @@ async function cmdBrain(options, flags, cwd, write, readStdin) {
         // Default recall = pure FTS order (nothing regresses). `--rerank` opts into the deterministic
         // lexical reranker (over-fetch → field-weighted reorder → trim) for a more on-point top-K.
         const rerank = flags.has('rerank');
-        // Default MATCH = all (AND) — precise. `--any` (OR) is recall-friendly for morphologically-varied
-        // queries: nominative query forms (репликация) don't prefix stored genitive forms (репликации),
-        // so AND can return 0 while a great KU exists (grounding already uses OR internally). Pairs well
-        // with --rerank: over-fetch broadly (OR), then reorder on-point first.
+        // Default MATCH = all (AND) — precise when it hits. If it returns zero hits, queryBrain retries
+        // once with OR and labels the result as broadened. Explicit `--any` still starts broad and is not
+        // labeled as a fallback. Pairs well with --rerank: over-fetch broadly, then reorder on-point first.
         const anyMatch = flags.has('any');
-        const { hits, error } = await queryBrain({
+        const queryResult = await queryBrain({
             query,
             limit,
             depsRoot: resolveDepsRoot(cwd),
@@ -1607,11 +1738,14 @@ async function cmdBrain(options, flags, cwd, write, readStdin) {
             ...(rerank ? { rerank: true } : {}),
             ...(anyMatch ? { match: 'any' } : {}),
         });
+        const { hits, error, broadened } = queryResult;
         if (asJson) {
-            write(JSON.stringify(hits));
+            write(JSON.stringify(broadened === true ? { hits, broadened: true } : hits));
             return 0;
         }
         write(`dz brain query "${query}"${source !== undefined ? ` --source ${source}` : ''}${anyMatch ? ' --any' : ''}${rerank ? ' --rerank' : ''}  —  ${hits.length} KU hit(s)`);
+        if (broadened === true)
+            write(`  broadened to any-term match: ${hits.length} hit(s)`);
         if (error !== undefined)
             write(`  (${error})`);
         for (const h of hits) {
@@ -3112,6 +3246,8 @@ export async function runCli(argv, io = {}) {
                 return await cmdBrain(options, flags, cwd, write, readStdin);
             case 'statusline':
                 return cmdStatusline(options, flags, cwd, write, readStdin);
+            case 'usage':
+                return cmdUsage(options, flags, cwd, write);
             case 'setup':
                 return await cmdSetup(options, flags, cwd, write);
             case 'pretrain':