@dzhechkov/harness-cli 0.3.195 → 0.3.198

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.195",
+  "version": "0.3.198",
   "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",
@@ -37,7 +37,15 @@
     "src",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit"
+  },
   "dependencies": {
+    "@dzhechkov/harness-core": "workspace:*",
     "@dzhechkov/harness-presets": "^0.5.0",
     "@dzhechkov/scout": "^0.8.0",
     "@dzhechkov/skills-devops": "^0.3.0",
@@ -53,8 +61,7 @@
     "@dzhechkov/skills-idea2prd": "^0.1.0",
     "@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.92"
+    "@dzhechkov/skills-website-cloner": "^0.1.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
@@ -72,12 +79,5 @@
     "url": "https://github.com/djd1m/dz-harness-hub.git",
     "directory": "packages/@dzhechkov/harness-cli"
   },
-  "homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/harness-cli#readme",
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "tsc -p tsconfig.json --noEmit"
-  }
-}
+  "homepage": "https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/harness-cli#readme"
+}

package/src/cli.ts

@@ -51,9 +51,12 @@ import {
   WORKFLOW_NAMES,
   importEcc,
   recordPattern,
+  resolveLearningBackend,
+  storeStats,
   consolidateSessions,
   pruneNoisePatterns,
   recallHybrid,
+  teachGuard,
   mirrorPatternsToVector,
   vectorMirrorEnabled,
   vectorTierStatus,
@@ -63,6 +66,8 @@ import {
   importRvfCheckpoint,
   statuslineData,
   writeFeatureAdrState,
+  computeUsage,
+  readUsageLimits,
   queryBookKnowledge,
   loadStorePatternsSync,
   bundleSkills,
@@ -122,6 +127,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>]
@@ -1037,11 +1043,14 @@ function cmdStatuslineFaRecord(options: Map<string, string>, cwd: string, write:
   if (recalled === undefined) return 1;
   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() } : {}),
   });
 
@@ -1049,7 +1058,7 @@ function cmdStatuslineFaRecord(options: Map<string, string>, cwd: string, write:
     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;
 }
 
@@ -1091,7 +1100,7 @@ function cmdStatusline(
     // 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);
@@ -1103,6 +1112,73 @@ function cmdStatusline(
   }
 }
 
+/**
+ * `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: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  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: string | null): string => {
+      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: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
   const projectRoot = options.get('project') ?? cwd;
 
@@ -1176,9 +1252,37 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
     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');
@@ -1191,6 +1295,23 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
   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') ||
@@ -1293,6 +1414,23 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
   // 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));
     } else {
@@ -1767,12 +1905,11 @@ async function cmdBrain(
     // 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),
@@ -1780,8 +1917,13 @@ async function cmdBrain(
       ...(rerank ? { rerank: true } : {}),
       ...(anyMatch ? { match: 'any' as const } : {}),
     });
-    if (asJson) { write(JSON.stringify(hits)); return 0; }
+    const { hits, error, broadened } = queryResult;
+    if (asJson) {
+      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) {
       const loc = h.chapter !== undefined
@@ -3365,6 +3507,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         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':

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 dzhechko
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.