@dzhechkov/harness-cli 0.3.223 → 0.3.225

package/package.json

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

package/src/cli.ts

@@ -144,7 +144,22 @@ import {
   buildChallengeBrief,
   pickAdversaryModel,
   CHALLENGE_QUESTIONS,
+  loadOutcomes,
+  renderOutcomes,
+  statsForKey,
+  selectAutoCost,
+  recordProvisional,
+  finalizeOutcome,
+  COST_LADDER,
+  splitScenarios,
+  budgetPlan,
+  selectWinner,
+  proseScopeOk,
+  renderProseDiff,
+  readScenarioIds,
+  DEFAULT_MAX_JUDGE_RUNS,
 } 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';
@@ -4558,6 +4573,144 @@ function cmdChallenge(options: Map<string, string>, flags: Set<string>, cwd: str
   return 0;
 }
 
+/**
+ * `dz routing` — inspect the learned cost-optimal routing outcome store (feature learned-cost-routing). Shows
+ * what `args.models[stage]='auto-cost'` currently believes per (stage, complexity-tier, model): gated
+ * attempts / successes / rate. Read-only.
+ *   --stage <s>   filter to one pipeline stage (code, qe, plan, …)
+ *   --json        raw store JSON
+ */
+function cmdRouting(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  let repoRoot = cwd;
+  try { repoRoot = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim() || cwd; } catch { /* not git */ }
+
+  const stage = options.get('stage');
+  const tier = options.get('tier');
+  const model = options.get('model');
+
+  // --select: resolve an `auto-cost` stage → the concrete model + escalate chain (the workflow shells out here
+  // because it is sandboxed with no fs). --family restricts to the coder's cross-family (qe guard); --ladder is
+  // the probe-filtered id set (account-specific Codex ids that answered).
+  if (flags.has('select')) {
+    if (!stage || !tier) { write('dz routing --select needs --stage and --tier'); return 1; }
+    const fam = options.get('family');
+    const family: Family | undefined = fam === 'claude' || fam === 'openai' ? fam : undefined;
+    const ladderCsv = options.get('ladder');
+    let ladder: readonly ModelRung[] | undefined;
+    if (ladderCsv !== undefined) {
+      const ids = new Set(ladderCsv.split(',').map((s) => s.trim()).filter(Boolean));
+      ladder = COST_LADDER.filter((r) => ids.has(r.id));
+    }
+    const statsFor = statsForKey(loadOutcomes(repoRoot), stage, tier);
+    const pick = selectAutoCost(stage, tier, statsFor, { ...(family ? { family } : {}), ...(ladder ? { ladder } : {}) });
+    write(JSON.stringify(pick));
+    return 0;
+  }
+
+  // --record-provisional / --finalize: the two-phase outcome label. The workflow calls these at stage end
+  // (provisional) and at the downstream gate (finalize, authoritative).
+  if (flags.has('record-provisional')) {
+    if (!stage || !tier || !model) { write('dz routing --record-provisional needs --stage --tier --model'); return 1; }
+    recordProvisional(repoRoot, stage, tier, model, flags.has('weak'));
+    write(`recorded provisional: ${stage}/${tier}/${model}${flags.has('weak') ? ' (weak-credit)' : ''}`);
+    return 0;
+  }
+  if (flags.has('finalize')) {
+    if (!stage || !tier || !model) { write('dz routing --finalize needs --stage --tier --model --success <true|false>'); return 1; }
+    const success = options.get('success') === 'true';
+    finalizeOutcome(repoRoot, stage, tier, model, success);
+    write(`finalized: ${stage}/${tier}/${model} → ${success ? 'success' : 'FAILURE'}`);
+    return 0;
+  }
+
+  // default / --json: inspect the learned table.
+  const store = loadOutcomes(repoRoot);
+  if (flags.has('json')) { write(JSON.stringify(store, null, 2)); return 0; }
+  write(renderOutcomes(store, stage));
+  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)) {
@@ -4834,6 +4987,10 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdFeatureAdrSetup(options, flags, cwd, write);
       case 'challenge':
         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':