@dzhechkov/harness-cli 0.3.224 → 0.3.225

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.224",
+  "version": "0.3.225",
   "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",
@@ -55,7 +55,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.118"
+    "@dzhechkov/harness-core": "0.3.119"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/src/cli.ts

@@ -151,8 +151,15 @@ import {
   recordProvisional,
   finalizeOutcome,
   COST_LADDER,
+  splitScenarios,
+  budgetPlan,
+  selectWinner,
+  proseScopeOk,
+  renderProseDiff,
+  readScenarioIds,
+  DEFAULT_MAX_JUDGE_RUNS,
 } from '@dzhechkov/harness-core';
-import type { Family, ModelRung } from '@dzhechkov/harness-core';
+import type { Family, ModelRung, Candidate as BtoCandidate, DimScores } from '@dzhechkov/harness-core';
 import type { SetupSpec } from '@dzhechkov/harness-core';
 import type { ProvenanceMode, PackVerdict, ClaudeUsageModel, PatternRecord, TargetName, BookKU, HarmonizeReport, UsageCalibrationPlan, ClaimFinding, RecallUsagePatternRow } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
@@ -4623,6 +4630,87 @@ function cmdRouting(options: Map<string, string>, flags: Set<string>, cwd: strin
   return 0;
 }
 
+/**
+ * `dz bto-optimize` — the deterministic engine BEHIND the `/bto-optimize` skill (feature bto-optimize-holdout).
+ * Adds dspy-MIPROv2 rigor the current evolutionary loop lacks: a hold-out split, a hard budget cap, and a
+ * no-regress-on-holdout winner selector. NOT a rival command — the skill delegates these steps; candidate-prose
+ * generation + judge scoring stay skill-side. `--json` on every subcommand.
+ *   --split --scenarios <csv|@file> [--holdout <r>]                 deterministic tune/holdout split
+ *   --plan --candidates K --rounds R --tune N --holdout M [--max C]  budget plan (trims to the cap)
+ *   --select --baseline <@json> --candidates <@json> [--tolerance t] accept only on holdout no-regress
+ *   --scope-check --original <f> --candidate <f>                     prose-only guard
+ *   --diff --original <f> --candidate <f>                            the prose diff to confirm
+ */
+function cmdBtoOptimize(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const json = flags.has('json');
+  const emit = (o: unknown): number => { write(JSON.stringify(o, null, json ? 2 : 0)); return 0; };
+  const readContained = (rel: string): string => {
+    // Containment (QE #traversal): an @file must stay under cwd — `@../../etc/passwd` must not read outside.
+    const rootAbs = resolve(cwd);
+    const abs = resolve(rootAbs, rel);
+    if (abs !== rootAbs && !abs.startsWith(rootAbs + sep)) throw new Error(`path escapes the working directory: ${rel}`);
+    return readFileSync(abs, 'utf-8');
+  };
+  const readJson = (spec: string | undefined): unknown => {
+    if (spec === undefined) return undefined;
+    const raw = spec.startsWith('@') ? readContained(spec.slice(1)) : spec;
+    return JSON.parse(raw);
+  };
+  try {
+    if (flags.has('split')) {
+      const sc = options.get('scenarios');
+      if (sc === undefined) { write('dz bto-optimize --split needs --scenarios <csv|@file>'); return 1; }
+      const ids = sc.startsWith('@') ? readScenarioIds(resolve(cwd, sc.slice(1))) : sc.split(',').map((s) => s.trim()).filter(Boolean);
+      const ratio = Number.parseFloat(options.get('holdout') ?? '');
+      const split = splitScenarios(ids, Number.isFinite(ratio) ? ratio : undefined);
+      if (json) return emit(split);
+      write(`tune (${split.tune.length}): ${split.tune.join(', ')}`);
+      write(`holdout (${split.holdout.length}): ${split.holdout.join(', ')}`);
+      return 0;
+    }
+    if (flags.has('plan')) {
+      const n = (k: string, d: number): number => { const v = Number.parseInt(options.get(k) ?? '', 10); return Number.isFinite(v) ? v : d; };
+      const max = Number.parseInt(options.get('max') ?? '', 10);
+      const plan = budgetPlan({ candidates: n('candidates', 5), rounds: n('rounds', 1), tuneCount: n('tune', 3), holdoutCount: n('holdout', 2) }, Number.isFinite(max) ? max : DEFAULT_MAX_JUDGE_RUNS);
+      if (json) return emit(plan);
+      write(`budget plan: ${plan.candidates} candidates × ${plan.rounds} round(s) → ${plan.tuneRuns} tune + ${plan.holdoutRuns} holdout = ${plan.totalRuns} judge run(s) (cap ${plan.cap}, ${plan.withinCap ? 'within cap' : 'OVER CAP'})`);
+      if (plan.trimmed) write(`  trimmed to fit: ${plan.trimmed}`);
+      return 0;
+    }
+    if (flags.has('select')) {
+      const baseline = readJson(options.get('baseline')) as { holdout: DimScores } | undefined;
+      const candidates = readJson(options.get('candidates')) as BtoCandidate[] | undefined;
+      if (!baseline || !Array.isArray(candidates)) { write('dz bto-optimize --select needs --baseline <@json {holdout}> and --candidates <@json [..]>'); return 1; }
+      const tol = Number.parseFloat(options.get('tolerance') ?? '');
+      const result = selectWinner(baseline, candidates, Number.isFinite(tol) ? { tolerance: tol } : {});
+      if (json) return emit(result);
+      write(result.winner ? `✓ winner: ${result.winner} — ${result.reason}` : `✗ no winner — ${result.reason}`);
+      return 0;
+    }
+    if (flags.has('scope-check') || flags.has('diff')) {
+      const o = options.get('original'); const c = options.get('candidate');
+      if (o === undefined || c === undefined) { write('needs --original <file> and --candidate <file>'); return 1; }
+      const origText = readContained(o);
+      const candText = readContained(c);
+      if (flags.has('scope-check')) {
+        const r = proseScopeOk(origText, candText);
+        if (json) return emit(r);
+        write(r.ok ? `✓ prose-only: ${r.reason}` : `✗ out of scope: ${r.reason}`);
+        return r.ok ? 0 : 1;
+      }
+      write(renderProseDiff(origText, candText));
+      return 0;
+    }
+    write('dz bto-optimize: pass --split | --plan | --select | --scope-check | --diff (see docs)');
+    return 1;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (json) { write(JSON.stringify({ error: msg })); return 1; }
+    write(`dz bto-optimize: ${msg}`);
+    return 1;
+  }
+}
+
 function cmdStats(cwd: string, write: Write): number {
   const baseDir = join(cwd, 'packages', '@dzhechkov');
   if (!existsSync(baseDir)) {
@@ -4901,6 +4989,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdChallenge(options, flags, cwd, write);
       case 'routing':
         return cmdRouting(options, flags, cwd, write);
+      case 'bto-optimize':
+        return cmdBtoOptimize(options, flags, cwd, write);
       case 'dashboard':
         return cmdDashboard(cwd, write);
       case 'roam':