@dzhechkov/harness-cli 0.3.193 → 0.3.197

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.193",
+  "version": "0.3.197",
   "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.90"
+    "@dzhechkov/harness-core": "0.3.94"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

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,
@@ -72,6 +77,7 @@ import {
   updateBrainSource,
   queryBrain,
   groundPrompt,
+  expandKu,
   reindexBrainVectors,
   buildPrimer,
   exportBrainSlice,
@@ -116,10 +122,12 @@ Usage:
   dz brain reindex [--json]                                            (snapshot, re-embed book-KU brain vectors, stamp current model)
   dz brain primer <slug> [--json]                                     (print a source's capability card — KU-type histogram + top decision moments)
   dz brain export --source <slug> --out <file>                        (export ONE source as a portable, lexical-only books.sqlite slice)
-  dz brain ground [<prompt>] [--k <N>] [--source <slug>] [--text]      (UserPromptSubmit hook: inject brain citations for a prompt; reads STDIN if no prompt)
+  dz brain ground [<prompt>] [--k <N>] [--source <slug>] [--text] [--budget <N>] [--full]  (UserPromptSubmit hook; --budget inlines top-K KUs within ~N tokens; --full = ~8000)
+  dz brain expand <kuId> [--source <slug>] [--json]                    (full-content lookup for a citation kuId; --json emits the full KU object)
   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>]
@@ -1035,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() } : {}),
   });
 
@@ -1047,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;
 }
 
@@ -1089,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);
@@ -1101,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;
 
@@ -1174,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');
@@ -1189,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') ||
@@ -1291,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 {
@@ -1556,6 +1696,13 @@ async function cmdVector(options: Map<string, string>, flags: Set<string>, cwd:
 /*  brain — the durable, cross-project knowledge brain (ADR §5.2 P0)    */
 /* ------------------------------------------------------------------ */
 
+/**
+ * Token budget used when `dz brain ground --full` is specified (chars/4 heuristic, approximate). A
+ * typical DDIA-scale KU is ~500–750 tokens; at k=5 the sum is well under 8000, so `--full` inlines
+ * everything the top-K recall returns in practice. Documented in the brain usage + wiki.
+ */
+const GROUND_FULL_BUDGET = 8_000;
+
 const BRAIN_USAGE = `dz brain — the durable, cross-project knowledge brain
 
 Usage:
@@ -1569,7 +1716,8 @@ Usage:
   dz brain reindex [--json]
   dz brain primer <slug> [--json]
   dz brain export --source <slug> --out <file>
-  dz brain ground [<prompt>] [--k <N>] [--source <slug>] [--text]
+  dz brain ground [<prompt>] [--k <N>] [--source <slug>] [--text] [--budget <N>] [--full]
+  dz brain expand <kuId>  [--source <slug>] [--json]
   dz brain init   [--project <dir>] [--k <N>]
 
   add:    default promotes THIS project's digitized-book KUs into the brain. The three --from-* modes
@@ -1591,6 +1739,15 @@ Usage:
           Always exits 0 — grounding is advisory and must never fail a prompt. Reranking is ON by
           default here (grounding wants the most on-point citation first). --text prints the raw
           citation block instead of the JSON wrapper (for manual inspection).
+          Three grounding tiers: (1) pointer (default, no flags) — one compact citation line per KU,
+          cheap every-turn; (2) model-driven expand (--budget N>0 / --full) — each citation carries
+          its kuId and the directive tells the model to pull full content via \`dz brain expand\`;
+          (3) budgeted eager (--budget N) — eager-inlines full content of the top-K KUs within ~N
+          tokens (chars/4 approx), worth-ranked; a KU that would overflow stays a pointer. --full =
+          --budget 8000. --budget 0 / absent = pointers-only.
+  expand: full-content lookup by kuId — the command the grounding directive names when --budget/--full
+          is used. Prints name, problem, pages, book, and the FULL content (untruncated); --json emits
+          the whole KU object. Exit 1 if the kuId is not found.
   init:   wires \`brain ground\` into .claude/settings.json as an opt-in UserPromptSubmit hook.`;
 
 /**
@@ -2009,12 +2166,28 @@ async function cmdBrain(
     const kRaw = options.get('k');
     const k = kRaw !== undefined ? Math.max(1, parseInt(kRaw, 10) || 5) : undefined;
 
-    const gopts: { prompt: string; depsRoot: string; k?: number; source?: string } = {
+    // brain-ground-expand: --budget N eager-inlines top-K KU content within ~N tokens (chars/4);
+    // --full = --budget GROUND_FULL_BUDGET; --budget 0 / absent ⇒ pointers-only (byte-identical).
+    const budgetRaw = options.get('budget');
+    let contentBudget: number | undefined;
+    if (budgetRaw !== undefined) {
+      const parsed = parseInt(budgetRaw, 10);
+      if (isNaN(parsed) || parsed < 0) {
+        write('dz brain ground: --budget must be a non-negative integer');
+        return 1;
+      }
+      contentBudget = parsed === 0 ? undefined : parsed; // 0 → pointer-only (FR-03.6)
+    } else if (flags.has('full')) {
+      contentBudget = GROUND_FULL_BUDGET;
+    }
+
+    const gopts: { prompt: string; depsRoot: string; k?: number; source?: string; contentBudget?: number } = {
       prompt,
       depsRoot: resolveDepsRoot(cwd),
     };
     if (k !== undefined) gopts.k = k;
     if (source !== undefined) gopts.source = source;
+    if (contentBudget !== undefined) gopts.contentBudget = contentBudget;
 
     const res = await groundPrompt(gopts);
     if (!res.emitted) return 0; // no relevant citations → inject nothing
@@ -2033,6 +2206,46 @@ async function cmdBrain(
     return 0;
   }
 
+  // ── dz brain expand <kuId> ───────────────────────────────────────────────────────────────────
+  // Full-content lookup by kuId — the command named in GROUNDING_DIRECTIVE_EXPAND (brain-ground-expand
+  // Tier 1). Prints the FULL `content` (+ name/problem/pages/book) for one citation the model wants
+  // to read; --json emits the whole KU object. Exit 1 on missing kuId / not-found.
+  if (sub === 'expand') {
+    const kuId = options.get('_positional_1');
+    if (!kuId) {
+      write('dz brain expand: a kuId is required');
+      write('  Example: dz brain expand ddia-ch05-ku01');
+      return 1;
+    }
+    const source = options.get('source');
+    const res = expandKu({
+      kuId,
+      depsRoot: resolveDepsRoot(cwd),
+      ...(source !== undefined ? { source } : {}),
+    });
+    if (res.error !== undefined) {
+      write(`dz brain expand: ${res.error}`);
+      return 1;
+    }
+    const ku = res.ku!;
+    if (asJson) {
+      write(JSON.stringify(ku, null, 2));
+      return 0;
+    }
+    const ch = ku.chapter !== undefined && ku.chapter !== '' ? `гл.${ku.chapter}` : '';
+    const pg = ku.pages !== undefined && ku.pages.length > 0 ? `с.${ku.pages.join('–')}` : '';
+    write(`kuId:    ${ku.kuId}`);
+    write(`book:    ${ku.book}`);
+    if (ch) write(`chapter: ${ch}`);
+    if (pg) write(`pages:   ${pg}`);
+    write(`name:    ${ku.name}`);
+    write(`problem: ${ku.problem}`);
+    write('');
+    write('content:');
+    write(ku.content);
+    return 0;
+  }
+
   // ── dz brain init ────────────────────────────────────────────────────────────────────────────
   // Opt-in: wire `dz brain ground` into .claude/settings.json as a UserPromptSubmit hook.
   // Idempotent read-merge-write — preserve every existing hook/key (e.g. the agentic-qe route hook).
@@ -3290,6 +3503,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':