@dzhechkov/harness-cli 0.3.205 → 0.3.207

package/README.md

@@ -1290,6 +1290,59 @@ in silence.
 Disable it by removing the two hook entries from `.claude/settings.json`; stop the daemon with
 `printf '{"op":"stop"}\n' | nc -U .dz/embed.sock`.
 
+#### Cleaning the store: dry-run first, always
+
+The learned store lives in a git-ignored `.dz/` and has no history. A wrong sweep cannot be undone,
+so both destructive surfaces **preview by default** and snapshot before they delete.
+
+```bash
+dz consolidate --prune-noise            # DRY RUN: names every record it would remove
+dz consolidate --prune-noise --apply    # snapshots to .dz/patterns-pre-prune-<ts>.json, then removes
+
+dz recall --forget <dzId>[,<dzId>…]     # DRY RUN
+dz recall --forget <dzId> --apply       # snapshots, then removes exactly those records
+```
+
+They cover **different** junk. `--prune-noise` removes what `isNoiseInsight` recognises: tool
+telemetry and system-wrapper "user responses" — text that was never a lesson. It cannot reach a record
+that is structurally fine but semantically worthless (this repo's store carried `mismatch probe A`,
+written by a `dz teach --project` path bug). `--forget` is for those: it takes explicit ids, which you
+find with `dz recall --all --json` or in the `never read` list of `dz recall --usage`.
+
+An unknown id exits `1` rather than reporting a successful removal of nothing. After `--forget`, run
+`dz vector reindex` — the lexical store and the vector mirror are separate copies.
+
+> **Behaviour change:** `--prune-noise` used to delete immediately. It now previews; pass `--apply`.
+
+#### Measuring the loop: usage, not size
+
+`N patterns stored` proves nothing about a learning system. The only question that matters is *were
+the lessons ever read?* — and the answer is usually humbling. So the statusline reports both:
+
+```
+🎓 dz: 103 patterns · 3 used · 🧠 2 sources
+```
+
+```bash
+dz recall --usage          # how many were read, which most, which NEVER
+dz recall --usage --json   # {totalPatterns, usedPatterns, neverReadPatterns, top, neverRead, …}
+```
+
+`neverRead` is the dead weight — patterns that have never once matched a real prompt. It is the input
+a future prune should consider, and the diagnostic that would have exposed a missing apply leg years
+earlier. (It also surfaces junk that should never have been learned: on this repo it immediately
+revealed patterns extracted from task-notification text.)
+
+Every injected hit is appended to `.dz/recall-usage.jsonl` — append-only, no locks, no schema. The
+embedding daemon opens the pattern store **read-only** and never writes, so it can never be the writer
+that tears a database file for a concurrent reader; the hook does the recording instead. The count and
+the last-read timestamp are derived from the **same records**, so they cannot disagree the way
+agentic-qe's do (its top row shows `usage_count = 1326` with `last_used_at: never`). The log is bounded:
+past `1 MiB` it compacts read events into aggregate rows that preserve both counts and timestamps.
+
+Recording never costs the injection: an unwritable log, a torn last line, a missing module — the hook
+still injects, still exits 0. Instrumentation must not break what it measures.
+
 #### Cross-lingual recall, and changing the embedding model
 
 The default embedder (`Xenova/paraphrase-multilingual-MiniLM-L12-v2`) is **multilingual**: a Russian

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA8JH,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;AA+iHD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkH5E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAuKH,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;AAmsHD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAkH5E"}

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, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, recallHybrid, teachGuard, mirrorPatternsToVector, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, 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, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, } 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
@@ -32,8 +32,8 @@ Usage:
   dz setup --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--project <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--install-driver] [--force] [--enrich]
   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 consolidate [--sessions-dir <dir>] [--project <dir>] [--no-mirror] [--prune-noise]
-  dz recall "<query>" [--limit <N>] [--semantic | --no-semantic] [--books [--book <slug>]] [--project <dir>] | dz recall --all [--json]
+  dz consolidate [--sessions-dir <dir>] [--project <dir>] [--no-mirror] [--prune-noise [--apply]]   (prune-noise: DRY-RUN by default; --apply snapshots then deletes)
+  dz recall "<query>" [--limit <N>] [--semantic | --no-semantic] [--books [--book <slug>]] [--project <dir>] | dz recall --all [--json] | dz recall --usage [--json] | dz recall --forget <dzId>[,<dzId>] [--apply]   (forget: dry-run default; snapshots before removing)
   dz vector status [--project <dir>] [--json]                          (semantic tier: engine, mirrored vs lexical counts, pending queue)
   dz vector reindex [--project <dir>] [--json]                         (snapshot, re-embed learned-pattern vectors, stamp current model)
   dz vector export <path> [--project <dir>]                            (portable VECTOR form (.rvf, opt-in RVF engine); patterns ship via recall --all --json)
@@ -932,7 +932,7 @@ function cmdStatusline(options, flags, cwd, write, readStdin) {
             write(JSON.stringify(data));
             return 0;
         }
-        let line = `🎓 dz: ${data.patterns} patterns · 🧠 ${data.brainSources} sources`;
+        let line = `🎓 dz: ${data.patterns} patterns${data.usedPatterns !== undefined ? ` · ${data.usedPatterns} used` : ''} · 🧠 ${data.brainSources} sources`;
         const branch = statuslineGitBranch(projectRoot);
         if (branch !== undefined)
             line += ` · ⎇ ${branch}`;
@@ -1341,9 +1341,27 @@ async function cmdConsolidate(options, flags, cwd, write) {
     // --prune-noise: RETRO-PRUNE legacy noise (tool telemetry + system-wrapper "responses") from
     // the lexical store AND the agentdb vector mirror BEFORE harvesting, so this run's watermark
     // never re-learns from junk. Best-effort — a prune error is reported, never fatal.
+    //
+    // DRY-RUN BY DEFAULT. The learned store lives in a git-ignored `.dz/` and has no history: a
+    // wrong sweep is unrecoverable. `--prune-noise` therefore only PREVIEWS; `--apply` performs the
+    // deletion, and snapshots the store to a restorable JSON export first. (Behaviour change: before
+    // this, `--prune-noise` deleted immediately and silently.)
+    const applyPrune = flags.has('apply');
     let pruned;
-    if (pruneNoise)
-        pruned = pruneNoisePatterns(projectRoot);
+    let pruneSnapshot;
+    if (pruneNoise) {
+        if (applyPrune) {
+            const dest = join(projectRoot, '.dz', `patterns-pre-prune-${Date.now()}.json`);
+            const snap = snapshotStore(projectRoot, dest);
+            if (snap.error === undefined)
+                pruneSnapshot = snap.path;
+            else
+                write(`  ⚠ snapshot failed (${snap.error}) — prune SKIPPED, the store is not versioned`);
+            if (snap.error !== undefined)
+                return 1; // never delete what we could not back up
+        }
+        pruned = pruneNoisePatterns(projectRoot, { dryRun: !applyPrune });
+    }
     // Throw-safety (QE P3): this command also runs DETACHED from the SessionEnd hook (stdio
     // ignored) — an uncaught store/watermark error would be fully invisible there. Catch, leave
     // an observable note next to the session markers, and report on stdout for manual runs.
@@ -1374,7 +1392,19 @@ async function cmdConsolidate(options, flags, cwd, write) {
     // Echo active flags in the header (learned pattern: flags must be visible in command output).
     write(`dz consolidate${pruneNoise ? ' (--prune-noise)' : ''}`);
     if (pruned !== undefined) {
-        write(`  pruned: ${pruned.lexicalRemoved} lexical, ${pruned.vectorRemoved} vector`);
+        const verb = pruned.dryRun === true ? 'would prune' : 'pruned';
+        write(`  ${verb}: ${pruned.lexicalRemoved} lexical, ${pruned.vectorRemoved} vector`);
+        for (const c of (pruned.candidates ?? []).slice(0, 10)) {
+            write(`    ${c.id}  ${c.text.replace(/\s+/g, ' ').slice(0, 72)}`);
+        }
+        const extra = (pruned.candidates?.length ?? 0) - 10;
+        if (extra > 0)
+            write(`    … and ${extra} more`);
+        if (pruned.dryRun === true && pruned.lexicalRemoved + pruned.vectorRemoved > 0) {
+            write('  DRY RUN — nothing deleted. Re-run with --apply to remove (snapshots first).');
+        }
+        if (pruneSnapshot !== undefined)
+            write(`  snapshot: ${pruneSnapshot}`);
         if (pruned.error !== undefined)
             write(`  Prune: ${pruned.error}`);
     }
@@ -1400,10 +1430,130 @@ async function cmdConsolidate(options, flags, cwd, write) {
     }
     return 0;
 }
+function recallUsagePatternRefs(projectRoot) {
+    return loadStoreRecords(projectRoot).map((record) => {
+        const pattern = recordToPattern(record);
+        return { dzId: record.id, pattern: pattern.pattern, domain: pattern.domain, reward: pattern.reward };
+    });
+}
+function readRecallUsageReport(projectRoot) {
+    let text = '';
+    const logPath = join(projectRoot, RECALL_USAGE_LOG_RELATIVE);
+    try {
+        if (existsSync(logPath))
+            text = readFileSync(logPath, 'utf-8');
+    }
+    catch {
+        text = '';
+    }
+    return buildRecallUsageReport(recallUsagePatternRefs(projectRoot), parseRecallUsageLog(text));
+}
+function fmtUsageRow(row) {
+    const last = row.lastReadAt !== undefined ? ` last=${row.lastReadAt}` : '';
+    const score = row.avgScore !== undefined ? ` avg=${row.avgScore.toFixed(3)}` : '';
+    const domain = row.domain !== undefined ? ` (${row.domain})` : '';
+    return `${row.reads}×${last}${score} ${row.dzId}${domain} ${row.pattern.slice(0, 100)}`;
+}
+function cmdRecallUsage(options, flags, projectRoot, write) {
+    const report = readRecallUsageReport(projectRoot);
+    if (flags.has('json')) {
+        write(JSON.stringify({
+            ...report,
+            log: join(projectRoot, RECALL_USAGE_LOG_RELATIVE),
+            retention: { maxBytes: RECALL_USAGE_LOG_MAX_BYTES },
+        }));
+        return 0;
+    }
+    const displayLimit = Math.max(1, parseInt(options.get('limit') ?? '20', 10) || 20);
+    write(`dz recall --usage  —  ${report.usedPatterns}/${report.totalPatterns} pattern(s) read, ${report.totalReads} read event(s)`);
+    write(`  log: ${RECALL_USAGE_LOG_RELATIVE} (bounded at ${RECALL_USAGE_LOG_MAX_BYTES} bytes)`);
+    if (report.invalidLines > 0)
+        write(`  skipped invalid/torn line(s): ${report.invalidLines}`);
+    if (report.unknownReadPatterns > 0)
+        write(`  usage rows for missing pattern id(s): ${report.unknownReadPatterns}`);
+    write('  most read:');
+    if (report.top.length === 0) {
+        write('    none yet');
+    }
+    else {
+        for (const row of report.top.slice(0, displayLimit))
+            write(`    ${fmtUsageRow(row)}`);
+        if (report.top.length > displayLimit)
+            write(`    ... ${report.top.length - displayLimit} more (use --json for the full list)`);
+    }
+    write('  never read:');
+    if (report.neverRead.length === 0) {
+        write('    none');
+    }
+    else {
+        for (const row of report.neverRead.slice(0, displayLimit))
+            write(`    ${row.dzId}${row.domain !== undefined ? ` (${row.domain})` : ''} ${row.pattern.slice(0, 100)}`);
+        if (report.neverRead.length > displayLimit)
+            write(`    ... ${report.neverRead.length - displayLimit} more (use --json for the full list)`);
+    }
+    return 0;
+}
+/**
+ * `dz recall --forget <dzId>[,<dzId>…] [--apply]` — remove NAMED records from the learned store.
+ *
+ * `--prune-noise` only removes what `isNoiseInsight` recognises. It cannot reach the other junk
+ * class: records that are structurally fine but were never lessons. This repo has two of them —
+ * `mismatch probe A` / `match probe B`, written into the LIVE store on 2026-07-07 by the
+ * `dz teach --project <relative>` path bug fixed in `83b1bac` (the relative root resolved to the
+ * cwd store instead of the temp project). The bug is gone; its residue is not, and no predicate
+ * will ever classify it.
+ *
+ * DRY-RUN BY DEFAULT, and it snapshots before deleting: `.dz/` is git-ignored and unversioned, so a
+ * mistaken id is unrecoverable. Use `dz recall --all --json` to find ids.
+ */
+async function cmdRecallForget(options, flags, projectRoot, write) {
+    const raw = options.get('forget') ?? '';
+    const ids = new Set(raw.split(',').map((s) => s.trim()).filter((s) => s !== ''));
+    if (ids.size === 0) {
+        write('dz recall --forget: no ids given (comma-separated dzIds; find them with `dz recall --all --json`)');
+        return 1;
+    }
+    // Use the CANONICAL store ids, not `patternRecordId(pattern)`. `removePatternsByIds` matches on
+    // `MemoryRecord.id`, and the two coincide only for records dz itself wrote (`dz teach` stores the
+    // hash as the id). A record seeded or migrated with a different id would be reported as "found",
+    // then silently NOT removed — the command would claim success while deleting nothing.
+    const known = new Map(loadStoreRecords(projectRoot).map((r) => [r.id, r.text]));
+    const found = [...ids].filter((id) => known.has(id));
+    const missing = [...ids].filter((id) => !known.has(id));
+    for (const id of found)
+        write(`  ${id}  ${(known.get(id) ?? '').replace(/\s+/g, ' ').slice(0, 72)}`);
+    for (const id of missing)
+        write(`  ${id}  (not in the store — nothing to forget)`);
+    if (found.length === 0) {
+        write('dz recall --forget: nothing matched.');
+        return 1;
+    }
+    if (!flags.has('apply')) {
+        write(`dz recall --forget: DRY RUN — ${found.length} record(s) would be removed. Re-run with --apply.`);
+        return 0;
+    }
+    const dest = join(projectRoot, '.dz', `patterns-pre-forget-${Date.now()}.json`);
+    const snap = snapshotStore(projectRoot, dest);
+    if (snap.error !== undefined) {
+        write(`dz recall --forget: snapshot failed (${snap.error}) — nothing removed; the store is not versioned`);
+        return 1;
+    }
+    const result = removePatternsByIds(projectRoot, new Set(found));
+    write(`dz recall --forget: removed ${result.removed} record(s)`);
+    write(`  snapshot: ${snap.path} (${snap.count} record(s))`);
+    if (result.error !== undefined)
+        write(`  ⚠ ${result.error}`);
+    write('  the vector mirror still holds them — run `dz vector reindex` to resync');
+    return 0;
+}
 async function cmdRecall(options, flags, cwd, write) {
     const projectRoot = resolve(cwd, options.get('project') ?? '.');
     const asJson = flags.has('json');
     const all = flags.has('all');
+    if (flags.has('usage'))
+        return cmdRecallUsage(options, flags, projectRoot, write);
+    if (options.has('forget'))
+        return cmdRecallForget(options, flags, projectRoot, write);
     // --all: dump the entire learned store (backend-agnostic, via loadStorePatternsSync).
     // With --json this is the portable export the agentdb-memory MCP bridge consumes.
     if (all) {