@dzhechkov/harness-cli 0.3.237 → 0.3.238

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.237",
+  "version": "0.3.238",
   "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",
@@ -57,7 +57,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.128"
+    "@dzhechkov/harness-core": "0.3.129"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7e8b772a6fa9ca0f36364cafd5ea996abeb62dc894c2f67f50ea7704a7a8824d"
+          "content": "ef6603652143fc1517c81506dad9d5e7b79e5d5138aad9f6281ad77492d58b71"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "cf6a3265890a8856ef31e3e7ac58026c15232c3c118ba0fcd1ce0d7590b84dd8"
+          "content": "8f8807920c7ddd901361eb5a602df9c85fa69726e47535a146937038eab6b281"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "b9af9be1bd31acd60e76275ff1055dd8e9b39b531b0c375467648f142b74d2c4"
+          "content": "5f5fbcc7c040a272f6af992ef1f9c39482b941d74dbcadec9f3d9008babcb08a"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6a51963ede51129e43524d62f3d757255a002dfec3df2c1dfa519af6f235a667"
+          "content": "420d1178a513e54f315095a17e9c5722543ca6cbdbebd9a674d4d50ef61b8aa0"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "1e7ef1d6e0796144999ad64d3650aeb4a2ccc7dfc66c5c5a8b705d783a9d0801"
+          "content": "8fbaf10d29b5733cf9445e1ef5804a3e124f733c3390a99937d2d8dc3b4cf02a"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "5180330ac6612542c80a74ea8e0983f5cd231e95bb3962eccdd65fbdbf6611a8"
+          "content": "131f23a50187e1be19875d4ccd76d8c354b1fbb8d193c03e73fda16ff64f51dc"
         }
       ]
     },
@@ -225,7 +225,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "461beed08ad6cfde7bbf559701fcbc6978f622c3951c80463c4e4943c538eff5"
+          "content": "3deb99917f3d8b4a5c9a3b0315bd65a3099ce2b508121cfa2bdeed19b7554d48"
         }
       ]
     },

package/src/cli.ts

@@ -64,6 +64,13 @@ import {
   recallHybrid,
   teachGuard,
   mirrorPatternsToVector,
+  mirrorEntriesToVector,
+  patternVectorEntry,
+  readMemoryLearningConfig,
+  promotePatterns,
+  quarantineExpiryCandidates,
+  pruneQuarantinePatterns,
+  clearAgentdbQuarantine,
   vectorMirrorEnabled,
   vectorTierStatus,
   resolveVectorEngine,
@@ -218,8 +225,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 [--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 consolidate [--sessions-dir <dir>] [--project <dir>] [--no-mirror] [--prune-noise [--apply]] [--prune-quarantine [--apply]]   (both prunes: DRY-RUN by default; --apply snapshots then deletes; prune-quarantine = expired unproven lessons ONLY, never coupled to noise)
+  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] | dz recall --promote <dzId>[,<dzId>] [--apply]   (forget/promote: dry-run default; forget snapshots before removing; promote lifts lesson-quarantine)
   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)
@@ -1515,6 +1522,16 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
     const receipt = await mirrorPatternsToVector(root, records, source);
     if (receipt.mirrored > 0) write(`  ↳ mirrored to vector tier (${receipt.engine ?? 'vector'})`);
   };
+  // lesson-quarantine FR-8: the fresh-teach mirror carries the qStatus marker so the hook daemon
+  // (which reads only the mirror's metadata) can exclude unproven lessons from auto-inject.
+  const emitMirrorQ = async (root: string, records: readonly PatternRecord[], source: string, quarantined: boolean): Promise<void> => {
+    if (flags.has('no-mirror') || records.length === 0 || !vectorMirrorEnabled(root)) return;
+    const entries = records
+      .map((r) => patternVectorEntry(r, source, quarantined ? { quarantined: true } : {}))
+      .filter((e): e is NonNullable<typeof e> => e !== undefined);
+    const receipt = await mirrorEntriesToVector(root, entries);
+    if (receipt.mirrored > 0) write(`  ↳ mirrored to vector tier (${receipt.engine ?? 'vector'})${quarantined ? ' [quarantined]' : ''}`);
+  };
 
   // `dz teach --harmonize` — documented ALIAS of `dz vector harmonize`: SEMANTIC dedup of the
   // learned store. ONE implementation (harmonizeVectorStore), two entry points (QR-6). Routed
@@ -1595,6 +1612,9 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
     const trained = await backend.train();
     if (trained.flushed > 0) {
       write(`↳ reinforced ${reinforce}`);
+      // lesson-quarantine: reinforcement IS promotion — keep the hook daemon's mirror in step.
+      const clearedQ = clearAgentdbQuarantine(projectRoot, [reinforce]);
+      if (clearedQ.cleared > 0) write(`  ↳ promoted out of quarantine (mirror updated)`);
       return 0;
     }
     // HIGH-fix: a no-match must NOT auto-teach the raw argument — callers pass dzIds or truncated
@@ -1629,6 +1649,8 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
       // 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`);
+        const clearedQ = clearAgentdbQuarantine(projectRoot, [verdict.dzId]);
+        if (clearedQ.cleared > 0) write('  ↳ promoted out of quarantine (mirror updated)');
         return 0;
       }
       write(`dz teach --guard: reinforce of ${verdict.dzId} did not flush (backend off or write failure) — teaching the lesson normally instead`);
@@ -1658,13 +1680,18 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
   // Tier-2 (ADR-005): persist through the unified @dzhechkov/memory store. recordPattern
   // folds any legacy .dz/patterns.jsonl into the backend (idempotent) and returns the
   // total count. The lossy `npx agentdb add` dual-write was removed in Tier-1 (audit #6).
-  const count = await recordPattern(projectRoot, entry);
+  // lesson-quarantine (opt-in): a fresh lesson is a HYPOTHESIS until it earns promotion.
+  const quarantineOn = readMemoryLearningConfig(projectRoot).quarantine;
+  const count = await recordPattern(projectRoot, entry, quarantineOn ? { quarantine: true } : {});
 
   write(`Learned: "${pattern.slice(0, 60)}${pattern.length > 60 ? '...' : ''}"`);
   write(`  Domain: ${domain}  Reward: ${reward}  Backend: memory (@dzhechkov/memory)`);
   write(`  Total patterns: ${count}`);
+  if (quarantineOn) {
+    write('  ⚠ quarantined: excluded from auto-inject, damped in recall — promote by confirming it (dz teach --reinforce "<text>") or dz recall --promote <dzId> --apply');
+  }
   // The lexical write above is durable — the vector mirror is strictly best-effort (I-3).
-  await emitMirror(projectRoot, [entry], 'dz-teach');
+  await emitMirrorQ(projectRoot, [entry], 'dz-teach', quarantineOn);
   return 0;
 }
 
@@ -1673,6 +1700,23 @@ async function cmdConsolidate(options: Map<string, string>, flags: Set<string>,
   const sessionsDirOpt = options.get('sessions-dir');
   const pruneNoise = flags.has('prune-noise');
 
+  // lesson-quarantine FR-7: expiry is a SEPARATE, explicit surface — never coupled to prune-noise
+  // (the recalled decay-vs-noise lesson: valid-but-unproven is not garbage). Dry-run by default.
+  if (flags.has('prune-quarantine')) {
+    const cfg = readMemoryLearningConfig(projectRoot);
+    const res = pruneQuarantinePatterns(projectRoot, { dryRun: !flags.has('apply'), expireDays: cfg.quarantineExpireDays });
+    if (!flags.has('apply')) {
+      write(`dz consolidate --prune-quarantine: DRY RUN — ${res.candidates.length} expired quarantined lesson(s) (> ${cfg.quarantineExpireDays}d, never reinforced)`);
+      for (const c of res.candidates) write(`  [${c.ageDays < 0 ? '?' : c.ageDays}d] ${c.dzId} ${c.text.slice(0, 70)}`);
+      if (res.candidates.length > 0) write('  → re-run with --apply to remove (snapshots first); or promote keepers: dz recall --promote <dzId> --apply');
+      return 0;
+    }
+    if (res.error !== undefined) { write(`dz consolidate --prune-quarantine: ${res.error}`); return 1; }
+    write(`dz consolidate --prune-quarantine: removed ${res.removed} expired quarantined lesson(s)`);
+    if (res.snapshot !== undefined) write(`  snapshot: ${res.snapshot}`);
+    return 0;
+  }
+
   // --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.
@@ -1890,12 +1934,53 @@ async function cmdRecallForget(
   return 0;
 }
 
+/**
+ * `dz recall --promote <dzId>[,<dzId>…] [--apply]` — lift quarantine from NAMED records
+ * (lesson-quarantine FR-6b). Dry-run by default, the --forget symmetry. Also clears the
+ * agentdb mirror's qStatus (best-effort) so the hook daemon stops excluding promoted lessons.
+ */
+async function cmdRecallPromote(
+  options: Map<string, string>,
+  flags: Set<string>,
+  projectRoot: string,
+  write: Write,
+): Promise<number> {
+  const ids = (options.get('promote') ?? '').split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+  if (ids.length === 0) {
+    write('dz recall --promote: no ids given (comma-separated dzIds; quarantined ones are marked ⚠q in recall)');
+    return 1;
+  }
+  if (!flags.has('apply')) {
+    const records = loadStoreRecords(projectRoot);
+    const found = ids.filter((id) => records.some((r) => r.id === id));
+    write(`dz recall --promote: DRY RUN — ${found.length}/${ids.length} id(s) match the store. Re-run with --apply to promote.`);
+    return 0;
+  }
+  const res = await promotePatterns(projectRoot, ids);
+  // Codex-QE finding 5: even on a mid-batch failure, the ALREADY-promoted records must get their
+  // mirror rows cleared — otherwise the canonical store and the hook-visible mirror split-brain.
+  if (res.promoted.length > 0) {
+    const cleared = clearAgentdbQuarantine(projectRoot, res.promoted);
+    if (cleared.cleared > 0) write(`  ↳ mirror updated (${cleared.cleared} row(s) un-quarantined in agentdb)`);
+    else if (cleared.error !== undefined) write(`  ⚠ mirror not updated (${cleared.error}) — run dz vector reindex to resync`);
+  }
+  if (!res.ok) {
+    write(`dz recall --promote: failed — ${res.error ?? 'unknown error'} (promoted so far: ${res.promoted.length})`);
+    return 1;
+  }
+  write(`dz recall --promote: promoted ${res.promoted.length} record(s)`);
+  if (res.notQuarantined.length > 0) write(`  already promoted (not quarantined): ${res.notQuarantined.join(', ')}`);
+  if (res.notFound.length > 0) write(`  not found: ${res.notFound.join(', ')}`);
+  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);
+  if (options.has('promote')) return cmdRecallPromote(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.
@@ -1994,9 +2079,16 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
   const lexLabel = result.lexicalBackend === 'sqlite' ? 'SQLite FTS5' : 'keyword (JSON)';
   const ranking = vectorOn ? `${lexLabel} + vector (${result.vectorEngine}) ranking` : `${lexLabel} ranking (lexical)`;
   write(`dz recall "${query}"  —  ${hits.length} hit(s), ${ranking}`);
+  let sawQuarantined = false;
   for (const h of hits) {
     const backendTag = vectorOn ? ` ⟨${h.backend}⟩` : '';
-    write(`  [${h.pattern.reward.toFixed(2)}] (${h.pattern.domain})${backendTag} ${h.pattern.pattern.slice(0, 80)}`);
+    const qTag = h.quarantined === true ? ' ⚠q' : '';
+    if (h.quarantined === true) sawQuarantined = true;
+    write(`  [${h.pattern.reward.toFixed(2)}] (${h.pattern.domain})${backendTag}${qTag} ${h.pattern.pattern.slice(0, 80)}`);
+  }
+  if (sawQuarantined) {
+    // The loop stays VISIBLE (ADR D2): a quarantined hit is shown, marked, and explained.
+    write('  ⚠q = quarantined (unproven hypothesis, rank damped) — confirm with dz teach --reinforce, or dz recall --promote <dzId> --apply');
   }
   if (result.vectorError !== undefined && mode !== 'lexical') {
     // Engine present but the semantic leg failed/timed out — one honest line, exit 0 (05 §2.3).