@dzhechkov/harness-cli 0.4.2 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "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",

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4e4049b871ded58ff38fc36b60387a2324610db81dedcb623fb9cce6e77b057b"
+          "content": "532051106b153c0d9bb7ad2abbeb71d418f88f1bc88e60a35e29cf42162af243"
         }
       ]
     },
@@ -95,7 +95,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a260f0e8d698ac142b38e33ef4d4ed0a21ccee96b179514bcb01bf81c5dce00f"
+          "content": "5bdc153e789ac180543e9b4955ea36666dc27b7238637b05875e048fc49ae30f"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "b8a9c6d50cea7eda1065d76adb83e7c853ed9d82db72e7b24f952598e9dbd9d9"
+          "content": "0183c01a98e232554a7460be48ee5fdf59dd3a7d09c719a31b08acc9c6b3528c"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4af214e9233bd8f37ab92b95b90fcf05bd46752ecdc0d9491484ee8a7e55c539"
+          "content": "c5bd1b0b852dd21de328494d7a99db336afbde4397b7c687d416f1a6f3c297b2"
         }
       ]
     },
@@ -175,7 +175,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "fa591b644f5abda81022a2cfe37996d739a2290ac46e09dcb958faa4e12be9f6"
+          "content": "4a164e5ac53ceec178463c1bdab9f80c1755311d5e4202c1f6234ca22c473b37"
         }
       ]
     },
@@ -195,7 +195,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c9847974744f5bfd383866eb1832e97cb856e73d6f65cad19abfb91f22998cae"
+          "content": "0a1097fc3a2294f934fc50f5871b287cfbc5ec85becdab914b7caeca42cb7d1a"
         }
       ]
     },
@@ -475,7 +475,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "3dd056f9d05712e45173b0911fc5900f0f52f8deba506d57c0e2b8281eb36a74"
+          "content": "fe8e5792626cf58678c1e2bcb809f63413655c2e171439157b74deb8b4fd80fb"
         }
       ]
     },
@@ -489,6 +489,16 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "test/trace-bundle-cli.test.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "fdaad63359ca7ce351e505e613b547bbc653e0847403edfae88d22a8a524b7a0"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "test/workflow-init-lint-clean.test.ts",

package/src/cli.ts

@@ -105,6 +105,7 @@ import {
   deriveUsageCalibration,
   normalizeClaudeUsageModelKey,
   readUsageLimits,
+  parseWeeklyResetAnchor,
   claimCheck,
   summarize,
   queryBookKnowledge,
@@ -222,6 +223,10 @@ import {
   selectAutoCost,
   recordProvisional,
   finalizeOutcome,
+  harvestStageOutcomes,
+  recommendModels,
+  planFeed,
+  GRADE_SUCCESS_FLOOR,
   COST_LADDER,
   splitScenarios,
   budgetPlan,
@@ -297,6 +302,8 @@ import {
   makeBacklogIO,
   harmonizeBacklog,
   transitionIdeas,
+  editIdea,
+  clearEmbedStale,
   BACKLOG_BACKENDS,
   applyDomainBoost,
   DZ_OWNED_TASK_TYPES,
@@ -326,6 +333,13 @@ import {
   mutationGateExitCode,
   summarizeMutationResults,
   renderMutationReport,
+  TRACE_BUNDLE_LEDGER_PATH,
+  TRACE_BUNDLE_SCHEMA,
+  TRACE_BUNDLE_RUN_META_FILE,
+  buildBundle,
+  serializeBundle,
+  parseBundle,
+  planImport,
 } from '@dzhechkov/harness-core';
 import type { MutationEntryResult, MutationObservation, MutationRegistryEntry } from '@dzhechkov/harness-core';
 import type { ReqeDebt } from '@dzhechkov/harness-core';
@@ -355,6 +369,8 @@ Usage:
   dz workflow blobs [--check]                               (list/self-check the subsystem blob registry)
   dz workflow-lint <script.js> [--plan <plan.json>] [--require-plan|--legacy] [--json]   (layer-1 gate; exit 0/1/3 — inconclusive is never a pass)
   dz workflow-trace <runDir|--slug <s>|--run <id>> [--invariants <plan.json>] [--html <out.html>] [--json]   (timeline + SEQ invariant runner)
+  dz workflow-trace export <run> --o <file> [--include-pairs --yes] [--strict]   (one run's telemetry as ONE movable file: events, not aggregates; degradation is typed and LOUD, --strict fails closed)
+  dz workflow-trace import <bundle> --into <root> [--force] [--with-pairs]       (reconstruct that run under an explicit root; FAIL-CLOSED — never writes over a run that already has content)
   dz install <npm-pkg> [--target <name>] [--project <dir>] [--force]
   dz bundle  [--preset <name> | --select id,id,...] [--out <dir>] [--skills-dir <dir>] [--force]   (portable self-contained skill bundles for a generic/LangGraph consumer)
   dz doctor  [--project <dir>] [--pubkey <path>] [--require-signing]   (health + signature check of installed packs)
@@ -381,6 +397,8 @@ Usage:
   dz backlog roulette [--pick <N>] [--seed <n>] [--commit] [--project <dir>] [--json]   (WEIGHTED draw over eligible ideas: alignment^alpha * recencyDecay * 1/effort, seeded; --pick N = ranked shortlist; --commit flips the pick to in-progress)
   dz backlog ship <id> [<id>…] [--reason <t>] [--dry-run] [--project <dir>] [--json]   (mark work DONE: new|enriched|in-progress → shipped, removing it from the roulette pool — run it after finishing a task; short id prefixes ok, ambiguous = loud error)
   dz backlog drop <id> [<id>…] [--reason <t>] [--dry-run] [--project <dir>] [--json]   (retire an idea: new|enriched|in-progress → dropped)
+  dz backlog edit <id> --text "<new>" | --append "<more>" [--dry-run] [--project <dir>] [--json]   (rewrite ONE idea's text, preserving every other field; re-embeds the dedup vector, and on a failed re-embed MARKS the record embedStale so dedup refuses to trust it — previous text preserved in .dz/backlog/edits.jsonl)
+  dz routing recommend [--tier <t>] [--apply] [--json]   (per-stage args.models suggestion from REAL telemetry — harness records + imported run-meta sidecars — printed WITH its basis: n runs, window, the grade-floor rule, skip reasons; qe is FORCED cross-family of code; --apply feeds .dz/routing-outcomes.json idempotently by runId)
   dz backlog reopen <id> [<id>…] [--reason <t>] [--dry-run] [--project <dir>] [--json]   (back to the pool: shipped|dropped|in-progress → new)
   dz backlog enrich <id> [--project <dir>] [--json]                        (stage the idea2prd input scaffold in features/<slug>/ and hand off to the idea2prd-manual skill — the CLI never fabricates a PRD)
   dz backlog jira <id> [--project <dir>] [--json]                          (draft a Jira issue via the configurable adapter (backlog.jira.adapter: jira-mcp|copilot-mcp|none); none writes an auditable jira-outbox/<id>.json stub)
@@ -1143,7 +1161,215 @@ function cmdWorkflowLint(options: Map<string, string>, flags: Set<string>, cwd:
 /** `dz workflow-trace` — timeline + invariant runner over a run's trace.jsonl. Scope is CAPPED
  * (AM-8): <runDir|--slug|--run>, --invariants, --html, --json. NO watch/filter/compare/search/
  * retention/access-control — adding one needs an ADR amendment (the surface test pins this). */
+/** The tool version stamped into a bundle's provenance. Unknown is honest; a throw is not. */
+function traceBundleToolVersion(): string {
+  try {
+    const req = createRequire(import.meta.url);
+    const pkg = req('../package.json') as { version?: unknown };
+    return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+  } catch { return 'unknown'; }
+}
+
+/** Resolve a run the SAME three ways the timeline reader does — positional, --slug, --run — so a
+ * bundle can never address a run by a scheme the rest of the command does not understand. */
+function resolveTraceRun(options: Map<string, string>, cwd: string, positional: string | undefined):
+  { runDir: string; slug: string | null; runId: string | null } | null {
+  const slug = options.get('slug');
+  const runId = options.get('run');
+  if (positional !== undefined && positional !== '') {
+    return { runDir: resolve(cwd, positional), slug: slug ?? null, runId: runId ?? null };
+  }
+  if (slug !== undefined) return { runDir: resolve(cwd, 'features', slug), slug, runId: runId ?? null };
+  if (runId !== undefined) return { runDir: resolve(cwd, '.dz', 'loop-trace', runId), slug: slug ?? null, runId };
+  return null;
+}
+
+/** Every harness workflow record under the project, already parsed. An unparseable file is SKIPPED
+ * here rather than guessed at — the pure half answers `unreadable` from what it is handed. */
+function readHarnessRecords(cwd: string): unknown[] {
+  const out: unknown[] = [];
+  const base = join(cwd, 'roam', 'claude-state');
+  if (!existsSync(base)) return out;
+  let sessions: string[] = [];
+  try { sessions = readdirSync(base); } catch { return out; }
+  for (const session of sessions) {
+    const dir = join(base, session, 'workflows');
+    if (!existsSync(dir)) continue;
+    let names: string[] = [];
+    try { names = readdirSync(dir); } catch { continue; }
+    for (const name of names) {
+      if (!name.endsWith('.json')) continue;
+      try { out.push(JSON.parse(readFileSync(join(dir, name), 'utf-8'))); } catch { /* skipped, never guessed */ }
+    }
+  }
+  return out;
+}
+
+/** `dz workflow-trace export` — one run's telemetry as ONE movable file. */
+function cmdWorkflowTraceExport(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const out = options.get('o') ?? options.get('out');
+  const run = resolveTraceRun(options, cwd, options.get('_positional_1'));
+  if (run === null || out === undefined || out === '') {
+    write('dz workflow-trace export: usage — dz workflow-trace export <runDir|--slug <s>|--run <id>> --o <file> [--include-pairs --yes] [--strict]');
+    return 1;
+  }
+  const wantPairs = flags.has('include-pairs');
+  if (wantPairs && !flags.has('yes')) {
+    write('dz workflow-trace export: --include-pairs needs --yes — training pairs may carry TARGET-REPO CODE and full prompts, so shipping them off this machine is a second, explicit decision');
+    return 1;
+  }
+
+  const readSlot = (abs: string, origin: string) =>
+    existsSync(abs)
+      ? { present: true as const, member: { origin, content: readFileSync(abs, 'utf-8') } }
+      : { present: false as const, reason: `absent on disk at ${origin}` };
+
+  const trace = readSlot(join(run.runDir, 'trace.jsonl'), 'trace.jsonl');
+  const checkpoints = readSlot(join(run.runDir, '.fa-state', 'checkpoints.jsonl'), '.fa-state/checkpoints.jsonl');
+
+  const ledgerAbs = join(cwd, TRACE_BUNDLE_LEDGER_PATH);
+  // An empty trailing line is not a malformed row — hand the pure half only real lines, or the
+  // bundle reports a phantom parse failure on every well-formed ledger (MEASURED on first run).
+  const ledgerLines = existsSync(ledgerAbs)
+    ? readFileSync(ledgerAbs, 'utf-8').split('\n').filter((line) => line.trim() !== '')
+    : null;
+
+  const pairFiles: { origin: string; content: string }[] = [];
+  if (wantPairs && run.slug !== null) {
+    const pairDir = join(cwd, '.dz', 'fa-training', run.slug);
+    if (existsSync(pairDir)) {
+      for (const name of readdirSync(pairDir)) {
+        if (!name.endsWith('.jsonl')) continue;
+        pairFiles.push({ origin: `.dz/fa-training/${run.slug}/${name}`, content: readFileSync(join(pairDir, name), 'utf-8') });
+      }
+    }
+  }
+
+  const bundle = buildBundle({
+    sourceRoot: cwd,
+    runAddress: options.get('_positional_1') ?? (run.slug !== null ? `--slug ${run.slug}` : `--run ${String(run.runId)}`),
+    slug: run.slug,
+    runId: run.runId,
+    toolVersion: traceBundleToolVersion(),
+    createdAt: null,
+    trace,
+    checkpoints,
+    ledgerLines,
+    ...(ledgerLines === null ? { ledgerReason: `no ledger at ${TRACE_BUNDLE_LEDGER_PATH}` } : {}),
+    includePairs: wantPairs,
+    pairFiles: wantPairs ? pairFiles : null,
+    records: readHarnessRecords(cwd),
+  });
+
+  try {
+    mkdirSync(dirname(resolve(cwd, out)), { recursive: true });
+    writeFileSync(resolve(cwd, out), serializeBundle(bundle));
+  } catch (err) {
+    write(`dz workflow-trace export: could not write ${out} — ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+
+  // Degradation is NAMED, never silent — and exactly one reason is actionable.
+  let degraded = 0;
+  if (!bundle.trace.present) { degraded++; write(`dz workflow-trace export: trace absent — ${bundle.trace.reason}`); }
+  if (!bundle.checkpoints.present) { degraded++; write(`dz workflow-trace export: checkpoints absent — ${bundle.checkpoints.reason}`); }
+  if (!bundle.ledger.present) { degraded++; write(`dz workflow-trace export: ledger absent — ${String(bundle.ledger.reason)}`); }
+  if (!bundle.runMeta.resolved) {
+    degraded++;
+    const reason = bundle.runMeta.reason;
+    write(reason === 'layout-unrecognised'
+      ? 'dz workflow-trace export: runMeta UNRESOLVED (layout-unrecognised) — the harness workflow-record layout CHANGED; update the reader in harness-core/src/trace-bundle.ts. This is the one reason that needs action'
+      : `dz workflow-trace export: runMeta unresolved (${reason}) — no action needed, this is history or absence, not a layout change`);
+  }
+  write(`dz workflow-trace export: wrote ${out} (${bundle.schema}; ledger rows scanned ${bundle.ledger.scanned}, matched ${bundle.ledger.matched}, malformed ${bundle.ledger.malformed})`);
+  if (degraded > 0 && flags.has('strict')) {
+    write(`dz workflow-trace export: --strict — ${degraded} member(s) degraded, failing closed`);
+    return 1;
+  }
+  return 0;
+}
+
+/** `dz workflow-trace import` — reconstruct a run under an explicit root. FAIL-CLOSED. */
+function cmdWorkflowTraceImport(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const file = options.get('_positional_1');
+  const into = options.get('into');
+  if (file === undefined || file === '' || into === undefined || into === '') {
+    write('dz workflow-trace import: usage — dz workflow-trace import <bundle.json> --into <root> [--force] [--with-pairs]');
+    return 1;
+  }
+  const abs = resolve(cwd, file);
+  if (!existsSync(abs)) { write(`dz workflow-trace import: no such bundle: ${file}`); return 1; }
+
+  const parsed = parseBundle(readFileSync(abs, 'utf-8'));
+  if (!parsed.ok) {
+    write(parsed.reason === 'unknown-schema'
+      ? `dz workflow-trace import: REFUSED — unknown bundle schema "${parsed.found}"; this dz reads ${TRACE_BUNDLE_SCHEMA}. A future bundle is never best-effort parsed`
+      : parsed.reason === 'member-shape'
+        ? `dz workflow-trace import: REFUSED — member "${parsed.member}" fails its shape check; a partial import is never left behind`
+        : 'dz workflow-trace import: REFUSED — the bundle is not parseable JSON');
+    return 1;
+  }
+  const bundle = parsed.bundle;
+
+  const root = resolve(cwd, into);
+  const runDirRel = bundle.provenance.slug !== null ? join('features', bundle.provenance.slug) : join('.dz', 'loop-trace', String(bundle.provenance.runId ?? 'unknown-run'));
+  const runDirAbs = join(root, runDirRel);
+  let runDirHasContent = false;
+  try { runDirHasContent = existsSync(runDirAbs) && readdirSync(runDirAbs).length > 0; } catch { runDirHasContent = false; }
+
+  let runIdentity: { slug: string | null; runId: string | null } | null = null;
+  const metaAbs = join(runDirAbs, TRACE_BUNDLE_RUN_META_FILE);
+  if (existsSync(metaAbs)) {
+    try {
+      const meta = JSON.parse(readFileSync(metaAbs, 'utf-8')) as { slug?: unknown; runId?: unknown };
+      runIdentity = {
+        slug: typeof meta.slug === 'string' ? meta.slug : null,
+        runId: typeof meta.runId === 'string' ? meta.runId : null,
+      };
+    } catch { runIdentity = null; }
+  }
+
+  const plan = planImport(bundle, {
+    runDir: runDirRel,
+    existingPaths: [],
+    runDirHasContent,
+    runIdentity,
+    force: flags.has('force'),
+    withPairs: flags.has('with-pairs'),
+    bundleName: basename(abs),
+  });
+
+  if (!plan.ok) {
+    for (const refusal of plan.refusals) write(`dz workflow-trace import: REFUSED ${refusal.path} — ${refusal.reason}`);
+    write('dz workflow-trace import: nothing was written');
+    return 1;
+  }
+
+  let written = 0;
+  const failures: string[] = [];
+  for (const entry of plan.writes) {
+    const target = join(root, entry.path);
+    try {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, entry.content);
+      written++;
+    } catch (err) {
+      failures.push(`${entry.path} — ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  // Report what ACTUALLY landed, computed from the writes, not from the plan.
+  for (const skipped of plan.refusals) write(`dz workflow-trace import: skipped ${skipped.path} — ${skipped.reason}`);
+  for (const failure of failures) write(`dz workflow-trace import: FAILED ${failure}`);
+  write(`dz workflow-trace import: wrote ${written} of ${plan.writes.length} member(s) under ${into}`);
+  return failures.length > 0 ? 1 : 0;
+}
+
 function cmdWorkflowTrace(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  // Two subcommands ride the SAME run addressing as the timeline reader (AM-8 keeps the surface
+  // capped; these are bundle transport, not new query verbs).
+  const sub = options.get('_positional_0');
+  if (sub === 'export') return cmdWorkflowTraceExport(options, flags, cwd, write);
+  if (sub === 'import') return cmdWorkflowTraceImport(options, flags, cwd, write);
   const runDirArg = options.get('_positional_0');
   const slug = options.get('slug');
   const runId = options.get('run');
@@ -2054,7 +2280,16 @@ function cmdUsage(
     const s = u.sessionPct === null ? 'n/a' : '~' + u.sessionPct + '%';
     const binding = hasModelLimits && u.weeklyBindingModel !== undefined ? ' ' + u.weeklyBindingModel + '-bound' : '';
     const w = u.weeklyPct === null ? 'n/a' : '~' + u.weeklyPct + '%' + binding;
-    write('usage: session ' + s + ' (resets ' + clock(u.sessionResetsAt) + ') · week ' + w + ' (resets ' + clock(u.weeklyResetsAt) + ') · estimated');
+    // The weekly reset is WEEKLY: print the anchor verbatim (weekday + offset), not a bare clock
+    // time — 'resets 08:59' reads as daily and hides the weekday (idea c8513be9: the bare form
+    // misread a Monday reading as '41 minutes after the boundary' when the boundary was Wednesday's).
+    const weeklyAnchorLabel = typeof lim.weeklyResetAnchor === 'string' && lim.weeklyResetAnchor !== ''
+      ? lim.weeklyResetAnchor
+      : clock(u.weeklyResetsAt);
+    write('usage: session ' + s + ' (resets ' + clock(u.sessionResetsAt) + ') · week ' + w + ' (resets ' + weeklyAnchorLabel + ') · estimated');
+    if (typeof lim.weeklyResetAnchor === 'string' && parseWeeklyResetAnchor(lim.weeklyResetAnchor)?.offsetMinutes === undefined) {
+      write('  ⚠ weeklyResetAnchor has NO utc offset — the boundary follows the SERVER timezone, not your account\'s true reset instant (measured: the same moment lands a week apart under UTC vs +03:00). Pin it: "' + lim.weeklyResetAnchor + ' +03:00" (your offset) in .dz/config.json');
+    }
     // re-QE debt surfacing (backlog 6b40e667): the moment someone checks usage is the moment a
     // usage-switched self-review debt should be visible. Best-effort — never breaks the contract.
     try {
@@ -8577,6 +8812,45 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
     return report.ok ? 0 : 1;
   }
 
+  // ── edit — replace/extend ONE idea's text (idea 1fde7bf6). The verb exists because a hand-edit
+  // does not re-embed: the dedup vector keeps describing the OLD text. editIdea owns the text change
+  // and MARKS the record embedStale; this layer owns the async re-embed and clears the mark ONLY
+  // after the vector tier confirms. A failed re-embed is loud here AND enforced at the harm point:
+  // classifyDedup refuses vector candidacy for a marked record (ADR-001).
+  if (sub === 'edit') {
+    const id = options.get('_positional_1');
+    if (id === undefined) return emitErr('an idea id is required: dz backlog edit <id> --text "<new>" | --append "<more>" [--dry-run]');
+    const report = editIdea(projectRoot, id, {
+      ...(options.get('text') !== undefined ? { text: options.get('text')! } : {}),
+      ...(options.get('append') !== undefined ? { append: options.get('append')! } : {}),
+      dryRun: flags.has('dry-run'),
+    });
+    let embed: 'ok' | 'stale' | 'skipped' = 'skipped';
+    if (report.ok && report.written && report.id !== undefined) {
+      const updated = readIdeas(projectRoot).find((i) => i.id === report.id);
+      if (updated !== undefined) {
+        const mirror = await mirrorIdeaVector(projectRoot, updated);
+        if (mirror.mirrored > 0 && mirror.error === undefined && clearEmbedStale(projectRoot, report.id)) embed = 'ok';
+        else embed = 'stale';
+      } else embed = 'stale';
+    }
+    if (json) {
+      write(JSON.stringify({ verb: 'edit', ...report, embed, exitCode: report.ok ? (embed === 'stale' ? 1 : 0) : 1 }, null, 2));
+      return report.ok ? (embed === 'stale' ? 1 : 0) : 1;
+    }
+    for (const e of report.errors) write(`dz backlog edit: ${e}`);
+    if (report.ok && report.id !== undefined) {
+      if (!report.written && !report.dryRun) write(`dz backlog edit: ${report.id} — text unchanged, nothing to do`);
+      else write(`dz backlog edit${report.dryRun ? ' (dry-run)' : ''}: ${report.id}\n  was: ${report.previousText?.slice(0, 100)}\n  now: ${report.newText?.slice(0, 100)}`);
+      if (report.written) {
+        if (embed === 'ok') write('  vector re-embedded (dedup form) — the record is fully consistent');
+        else write('  ⚠ vector NOT re-embedded — the record is MARKED embedStale: dedup will refuse to trust its similarity until `dz vector reindex` repairs it (the text edit itself landed)');
+      }
+      if (report.dryRun) write('  (dry-run — nothing written; re-run without --dry-run to apply)');
+    }
+    return report.ok ? (embed === 'stale' ? 1 : 0) : 1;
+  }
+
   if (sub === 'enrich') {
     const id = options.get('_positional_1');
     if (id === undefined) return emitErr('an idea id is required: dz backlog enrich <id>');
@@ -8667,6 +8941,55 @@ function cmdRouting(options: Map<string, string>, flags: Set<string>, cwd: strin
   let repoRoot = cwd;
   try { repoRoot = execSync('git rev-parse --show-toplevel', { cwd, encoding: 'utf-8' }).trim() || cwd; } catch { /* not git */ }
 
+  // ── recommend — harvest real telemetry, print per-stage picks WITH THE BASIS, optionally feed the
+  // store (a9c3dd5c fn 3, ADR-001). Sources: live harness records + imported run-meta.json sidecars.
+  if (options.get('_positional_0') === 'recommend') {
+    const records: unknown[] = readHarnessRecords(repoRoot);
+    // imported runs (trace-bundle ADR-001 D4): run-meta sidecars carry runMeta.records of the SAME shape
+    for (const base of [join(repoRoot, 'features'), join(repoRoot, '.dz', 'loop-trace')]) {
+      if (!existsSync(base)) continue;
+      let names: string[] = [];
+      try { names = readdirSync(base); } catch { continue; }
+      for (const name of names) {
+        const sidecar = join(base, name, 'run-meta.json');
+        if (!existsSync(sidecar)) continue;
+        try {
+          const meta = JSON.parse(readFileSync(sidecar, 'utf-8')) as { runMeta?: { resolved?: boolean; records?: unknown[] } };
+          if (meta.runMeta?.resolved === true && Array.isArray(meta.runMeta.records)) records.push(...meta.runMeta.records);
+        } catch { /* an unreadable sidecar contributes nothing — counted below as noResult */ }
+      }
+    }
+    const harvest = harvestStageOutcomes(records);
+    const rec = recommendModels(harvest, { ...(options.get('tier') !== undefined ? { tier: options.get('tier')! } : {}) });
+    if (flags.has('apply')) {
+      const fedPath = join(repoRoot, '.dz', 'routing-fed.json');
+      let alreadyFed: string[] = [];
+      try { alreadyFed = JSON.parse(readFileSync(fedPath, 'utf-8')) as string[]; } catch { /* first apply */ }
+      const plan = planFeed(harvest.samples, alreadyFed);
+      for (const sample of plan.toFeed) finalizeOutcome(repoRoot, sample.stage, sample.tier, sample.model, sample.success);
+      try {
+        mkdirSync(join(repoRoot, '.dz'), { recursive: true });
+        writeFileSync(fedPath, JSON.stringify(plan.fedAfter));
+      } catch (e) {
+        write(`dz routing recommend: fed ${plan.toFeed.length} sample(s) but could NOT persist the fed-set — a re-apply WILL double-count: ${(e as Error).message}`);
+        return 1;
+      }
+      write(`dz routing recommend --apply: fed ${plan.toFeed.length} sample(s) into .dz/routing-outcomes.json${plan.skippedRuns.length > 0 ? `; skipped ${plan.skippedRuns.length} already-fed run(s) (idempotent by runId)` : ''}`);
+    }
+    if (flags.has('json')) {
+      write(JSON.stringify({ recommendation: rec, exitCode: 0 }, null, 2));
+      return 0;
+    }
+    write(`dz routing recommend — args.models suggestion from ${rec.basis.runsUsed} run(s)${rec.basis.window !== null ? ` (${rec.basis.window.min.slice(0, 10)}..${rec.basis.window.max.slice(0, 10)})` : ''}:`);
+    for (const s of rec.perStage) {
+      write(`  ${s.stage.padEnd(14)} ${s.spec.padEnd(20)} ${s.insufficientData ? '[insufficient data — cold-start pick]' : '[quality bar met]'} ${s.pick.evidence}`);
+    }
+    write(`  basis: ${rec.basis.rule}`);
+    write(`  basis: skipped records — no result ${rec.basis.skipped.noResult}, no modelsUsed ${rec.basis.skipped.noModels} (predates model routing — history, not an error), no grade ${rec.basis.skipped.noGrade}, unknown model ${rec.basis.skipped.unknownModel}`);
+    write(`  basis: ${rec.basis.crossFamilyNote}`);
+    return 0;
+  }
+
   const stage = options.get('stage');
   const tier = options.get('tier');
   const model = options.get('model');