@dzhechkov/harness-cli 0.3.205 → 0.3.207

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.205",
+  "version": "0.3.207",
   "description": "The dz CLI — install AI skills for Claude Code, Codex, OpenCode, Hermes, OpenClaude, GitHub Copilot. 35 commands, 13 presets, 6 platform targets.",
   "type": "module",
   "license": "MIT",
@@ -54,7 +54,7 @@
     "@dzhechkov/skills-reverse-engineering": "^0.1.0",
     "@dzhechkov/skills-presentation-storyteller": "^0.1.0",
     "@dzhechkov/skills-website-cloner": "^0.1.0",
-    "@dzhechkov/harness-core": "0.3.104"
+    "@dzhechkov/harness-core": "0.3.106"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/src/cli.ts

@@ -55,6 +55,8 @@ import {
   storeStats,
   consolidateSessions,
   pruneNoisePatterns,
+  removePatternsByIds,
+  snapshotStore,
   recallHybrid,
   teachGuard,
   mirrorPatternsToVector,
@@ -74,6 +76,9 @@ import {
   summarize,
   queryBookKnowledge,
   loadStorePatternsSync,
+  patternRecordId,
+  loadStoreRecords,
+  recordToPattern,
   bundleSkills,
   brainHome,
   listBrain,
@@ -87,8 +92,12 @@ import {
   exportBrainSlice,
   importBrainSlice,
   registerKusToBrain,
+  RECALL_USAGE_LOG_RELATIVE,
+  RECALL_USAGE_LOG_MAX_BYTES,
+  parseRecallUsageLog,
+  buildRecallUsageReport,
 } from '@dzhechkov/harness-core';
-import type { ClaudeUsageModel, PatternRecord, TargetName, BookKU, HarmonizeReport, UsageCalibrationPlan, ClaimFinding } from '@dzhechkov/harness-core';
+import type { ClaudeUsageModel, PatternRecord, TargetName, BookKU, HarmonizeReport, UsageCalibrationPlan, ClaimFinding, RecallUsagePatternRow } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 
@@ -112,8 +121,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)
@@ -1102,7 +1111,7 @@ function cmdStatusline(
       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}`;
     if (data.consolidatedAgeH !== undefined) line += ` · ⟳ ${data.consolidatedAgeH}h`;
@@ -1554,8 +1563,24 @@ async function cmdConsolidate(options: Map<string, string>, flags: Set<string>,
   // --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: ReturnType<typeof pruneNoisePatterns> | undefined;
-  if (pruneNoise) pruned = pruneNoisePatterns(projectRoot);
+  let pruneSnapshot: string | undefined;
+  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.
@@ -1585,7 +1610,17 @@ async function cmdConsolidate(options: Map<string, string>, flags: Set<string>,
   // 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}`);
   }
   write(`  Sessions dir: ${result.sessionsDir}  (${sourceLabel[result.source]})`);
@@ -1606,10 +1641,132 @@ async function cmdConsolidate(options: Map<string, string>, flags: Set<string>,
   return 0;
 }
 
+function recallUsagePatternRefs(projectRoot: string): { dzId: string; pattern: string; domain: string; reward: number }[] {
+  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: string) {
+  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: RecallUsagePatternRow): string {
+  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: Map<string, string>, flags: Set<string>, projectRoot: string, write: Write): number {
+  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: Map<string, string>,
+  flags: Set<string>,
+  projectRoot: string,
+  write: Write,
+): Promise<number> {
+  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: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
   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.