@dzhechkov/harness-cli 0.3.247 → 0.3.250

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.247",
+  "version": "0.3.250",
   "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",
@@ -41,6 +41,7 @@
     "sbom.json"
   ],
   "dependencies": {
+    "@dzhechkov/harness-core": "^0.3.141",
     "@dzhechkov/harness-presets": "^0.5.0",
     "@dzhechkov/scout": "^0.8.0",
     "@dzhechkov/skills-devops": "^0.3.0",
@@ -56,8 +57,7 @@
     "@dzhechkov/skills-idea2prd": "^0.1.0",
     "@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.138"
+    "@dzhechkov/skills-website-cloner": "^0.1.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "129ee8a3fc96a1edda2258d02cd6dc4b8df2ab766f3b03ddb38f1559f0c0d9b9"
+          "content": "1559995482381fd6ac146e6d229cb7d33476cdca8fad21fd361467dd698bd065"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "894d5779615292e57a6b5c204ebd04cef4b065e3fe4d8546c0f3dfbe0fb22529"
+          "content": "e41e9538474ad80901474841e66f3be8b9f4fdc24f85b4168a13958f19f0762c"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "aaaf1d89fb27f39c125c3404b37d57f9251fe62d7993f79df5696944ae8bddcf"
+          "content": "038b4bf4c9295202129662e1caf3b8b139c91f69b2e292373066154b644cc97c"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "dfdfb4feeb07bf037194a1aa7da4f956e88da30ec8c1848fa2e989d82ed34a0b"
+          "content": "dafbac9c642da206ddfadb9081f01ef2a4cfba98dee719ef64200241d2b76726"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "16065506fcf54ea10fab7342da217ff2416818c20e05dd998036a75075083330"
+          "content": "4e22f0553a19181eea750db59bd3eec84fd880473ac523705a1a26197665e87e"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "967efe0f790775d915f31665e270490794a8ca4bdbecd0844562edda2edf42d9"
+          "content": "9a32862f99d3d0211e08ea49c7091f5697acdd2789ac05137203abd6ed7a9b3e"
         }
       ]
     },
@@ -225,7 +225,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a82b15dd9d166764479528e9f9ede45fc39d1b4068a96f19f158aa5a4c03369b"
+          "content": "2e013ab73b4eb3dd248ed0fbbd5c050911ad667bb78054fde0bb021fbd1815db"
         }
       ]
     },

package/src/cli.ts

@@ -200,12 +200,35 @@ import {
   renderContentProbe,
   findNonRegistrableSkillDirs,
   assembleCompoundingReport,
+  scoreRun,
+  renderScorecard,
   renderCompoundingReport,
   readReinforcementState,
   readQuarantineState,
   registrationExitCode,
   renderRegistrationReport,
+  // Smart Backlog (feature smart-backlog) — goal-directed idea pipeline over the Brain vector engine.
+  readBacklogConfig,
+  readIdeas,
+  writeIdeas,
+  ideaId,
+  dedupIdea,
+  readGoalMap,
+  alignIdea,
+  mirrorIdeaVector,
+  snapshotIdeas,
+  spinRoulette,
+  rankRoulette,
+  seededRng,
+  eligibleIdeas,
+  stageEnrichment,
+  buildJiraDraft,
+  resolveJiraAdapter,
+  makeBacklogIO,
+  harmonizeBacklog,
+  BACKLOG_BACKENDS,
 } from '@dzhechkov/harness-core';
+import type { IdeaRecord, IdeaStatus } 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, GateExecution, GateStep } from '@dzhechkov/harness-core';
@@ -237,6 +260,15 @@ Usage:
   dz delivery-check --slug <slug> [--context-only] [--findings <f.json>] [--strict] [--author <model>] [--json]   (portable Step-10 Delivery Gate: prints the 4-plane review brief + artifact probes; --findings classifies a fed-back review into a fail-closed ready|blocked hand-off and writes features/<slug>/10_delivery_review.md; --strict exits 1 on blocked)
   dz skills-verify [--dir <project>] [--expect a,b] [--static] [--strict] [--json]   (does .claude/skills/ actually REGISTER? --static = instant layout scan for CI; default reads the authoritative system/init listing from a real session. exit 0 pass / 1 fail / 2 inconclusive — never a false pass)
   dz compounding [--project <dir>] [--json]   (honest learning-loop payoff report: pool write-only ratio, guard repeat-violation trajectory, cold-vs-warm replay readiness, instrumentation health — a gate without enough data says INSUFFICIENT_DATA, never a fake verdict)
+  dz score --slug <feature> [--project <dir>] [--json]   (process scorecard for ONE feature-adr run, from its artifacts: ADR confirmation, discrimination, cross-model QE grade, live verification, README-first, learning loop, amendments — descriptive-only, a low score exits 0)
+  dz backlog add "<idea>" [--effort 1-5] [--proposal <text>] [--dry-run] [--project <dir>] [--json]   (capture an idea: semantic dedup against existing ideas via the Brain vector engine (DUPLICATE>=0.92 merges, RELATED links, NEW creates) + GoalMap alignment; --dry-run classifies without writing)
+  dz backlog list [--status <s>] [--goal <id>] [--project <dir>] [--json]   (list captured ideas, filterable by status/goal)
+  dz backlog show <id> [--project <dir>] [--json]                          (full record for one idea)
+  dz backlog goals [--validate] [--project <dir>] [--json]                 (list/validate the compass at .dz/backlog/goals.json)
+  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 (the only mutation))
+  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)
+  dz backlog harmonize [--apply] [--threshold <0-1>] [--project <dir>] [--json]   (batch semantic dedup of the backlog ideas; --dry-run default, --apply snapshots first)
   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)
@@ -2215,6 +2247,8 @@ async function cmdVector(options: Map<string, string>, flags: Set<string>, cwd:
       return report.error !== undefined ? 1 : 0;
     }
     if (report.error !== undefined) {
+      // Honest failure/skip. Under a non-agentdb engine backlog is reported `skipped` (it never touches the
+      // shared manifest); a model bump needs a FULL reindex under the agentdb engine. Surface it, exit 1.
       write(`dz vector reindex: ${report.error}`);
       return 1;
     }
@@ -5625,6 +5659,87 @@ function nameFor(t: { file: string; name?: string }, outcome: 'pass' | 'fail' |
  *   --author <model>         cosmetic: the reviewer to dispatch, printed alongside the brief
  *   --json                   machine contract { planesChecked, planesSkipped, findings, handoff, artifact }
  */
+/**
+ * `dz score --slug <feature>` — score a feature-adr RUN's process discipline from its artifacts
+ * (feature dz-score, Reading C). Descriptive-only: exit 0 on any score; non-zero only on usage errors.
+ */
+function cmdScore(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const json = flags.has('json');
+  if (flags.has('help')) {
+    const usage = 'dz score --slug <feature> [--project <dir>] [--json] — process scorecard for one feature-adr run (descriptive-only, never a gate)';
+    if (json) write(JSON.stringify({ help: usage, exitCode: 0 })); // --json stays ONE document even for help
+    else {
+      write(usage);
+      write('  disciplines: ADR confirmation · discrimination · cross-model QE · live verification · README-first · learning loop · amendments');
+      write('  descriptive-only, never a gate: a low score exits 0');
+    }
+    return 0;
+  }
+  for (const flag of flags) {
+    if (!new Set(['json', 'help']).has(flag)) {
+      write(json ? JSON.stringify({ error: `unknown option --${flag}`, exitCode: 1 }) : `dz score: unknown option --${flag}\n  allowed: --slug <feature>, --project <dir>, --json`);
+      return 1;
+    }
+  }
+  for (const key of options.keys()) {
+    if (key.startsWith('_positional_') || !new Set(['slug', 'project']).has(key)) {
+      const what = key.startsWith('_positional_') ? `unexpected argument "${options.get(key)}"` : `unknown option --${key}`;
+      write(json ? JSON.stringify({ error: what, exitCode: 1 }) : `dz score: ${what}\n  allowed: --slug <feature>, --project <dir>, --json`);
+      return 1;
+    }
+  }
+  const slug = options.get('slug') ?? '';
+  // The delivery-check traversal lesson, upgraded to a WHITELIST: `.` slipped the blacklist and
+  // silently aggregated the entire features/ tree as one "run" (Codex QE #2).
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug) || slug === '.' || slug === '..' || slug.includes('..')) {
+    write(json ? JSON.stringify({ error: 'a plain --slug <feature> is required (no path separators)', exitCode: 1 }) : 'dz score: a plain --slug <feature> is required (no path separators)');
+    return 1;
+  }
+  const root = resolve(cwd, options.get('project') ?? '.');
+  const dir = join(root, 'features', slug);
+  if (!existsSync(dir)) {
+    write(json ? JSON.stringify({ error: `no run at features/${slug}/`, exitCode: 1 }) : `dz score: no run at features/${slug}/`);
+    return 1;
+  }
+
+  // Gather the artifact texts (bounded, best-effort — an unreadable file is skipped, not fatal).
+  const artifacts: Record<string, string> = {};
+  let fileBudget = 200; // a run has ~a dozen artifacts; a wide tree must degrade, not exhaust memory
+  const walk = (d: string, prefix: string, depth: number): void => {
+    if (depth > 3 || fileBudget <= 0) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(d);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (fileBudget <= 0) return;
+      const full = join(d, name);
+      const rel = prefix === '' ? name : `${prefix}/${name}`;
+      try {
+        // lstat: a symlinked artifact (or a symlinked features/<slug> subtree) could smuggle
+        // OUTSIDE text into the scorecard's evidence (Codex QE #5).
+        const st = lstatSync(full);
+        if (st.isSymbolicLink()) continue;
+        if (st.isDirectory()) walk(full, rel, depth + 1);
+        else if (st.isFile() && name.endsWith('.md') && st.size < 512 * 1024) {
+          artifacts[rel] = readFileSync(full, 'utf-8');
+          fileBudget -= 1;
+        }
+      } catch {
+        /* skip unreadable */
+      }
+    }
+  };
+  walk(dir, '', 0);
+
+  const card = scoreRun(slug, artifacts);
+  if (json) write(JSON.stringify({ ...card, exitCode: 0 }, null, 2));
+  else write(renderScorecard(card));
+  return 0;
+}
+
 /**
  * `dz compounding` — does the learning loop actually PAY? (feature compounding, scout C2.)
  * Gathers the facts (store rows, apply-leg usage log, guard audit) and hands them to the PURE
@@ -6065,6 +6180,241 @@ function cmdDeliveryCheck(options: Map<string, string>, flags: Set<string>, cwd:
   return 0;
 }
 
+/* ------------------------------------------------------------------ */
+/*  backlog — the Smart Backlog idea pipeline (feature smart-backlog)   */
+/* ------------------------------------------------------------------ */
+
+/** Thin dispatcher — ALL logic lives in harness-core/src/backlog.ts (05 architecture: handlers stay dumb). */
+async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
+  const projectRoot = resolve(cwd, options.get('project') ?? '.');
+  const json = flags.has('json');
+  const sub = options.get('_positional_0');
+  const cfg = readBacklogConfig(projectRoot);
+
+  const emitErr = (msg: string): number => {
+    write(json ? JSON.stringify({ error: msg, exitCode: 1 }) : `dz backlog: ${msg}`);
+    return 1;
+  };
+
+  if (sub === 'add') {
+    const text = (options.get('_positional_1') ?? '').trim();
+    if (text === '') return emitErr('an idea text is required: dz backlog add "<idea>"');
+    const effort = Number(options.get('effort') ?? cfg.roulette.defaultEffort);
+    const dryRun = flags.has('dry-run');
+    const verdict = await dedupIdea(projectRoot, text, cfg);
+    if (verdict.action === 'duplicate') {
+      // DUPLICATE ⇒ snapshot + reinforce the existing root; NO new record (ADR-002 T-002b).
+      const ideas = readIdeas(projectRoot);
+      const match = ideas.find((i) => i.id === verdict.matchedId);
+      if (!dryRun && match !== undefined) {
+        const snap = snapshotIdeas(projectRoot, join(projectRoot, '.dz', 'backlog', `ideas.pre-merge-${Date.now()}.jsonl`));
+        if (snap.error !== undefined) return emitErr(snap.error);
+        match.uses += 1;
+        writeIdeas(projectRoot, ideas);
+      }
+      if (json) write(JSON.stringify({ action: 'duplicate', matchedId: verdict.matchedId, cosine: verdict.cosine, exitCode: 0 }, null, 2));
+      else write(`dz backlog: DUPLICATE of ${verdict.matchedId} (cosine ${verdict.cosine.toFixed(3)}${verdict.exactTextOnly ? ', exact-text' : ''}) — reinforced, no new record`);
+      return 0;
+    }
+    const goalMap = readGoalMap(projectRoot);
+    const align = await alignIdea(projectRoot, text, goalMap);
+    const createdTs = new Date().toISOString();
+    const rec: IdeaRecord = {
+      id: ideaId(text, createdTs),
+      text,
+      status: 'new',
+      createdTs,
+      effort: Number.isFinite(effort) ? Math.max(1, Math.min(5, Math.floor(effort))) : cfg.roulette.defaultEffort,
+      goalId: align.goalId,
+      goalAlignment: align.goalAlignment,
+      relatedIds: [...verdict.relatedIds],
+      uses: 0,
+      tags: [],
+    };
+    const proposal = options.get('proposal');
+    if (proposal !== undefined) rec.proposal = proposal; // agent prose ONLY — the CLI never fabricates it
+    if (dryRun) {
+      if (json) write(JSON.stringify({ action: verdict.action, dryRun: true, idea: rec, exitCode: 0 }, null, 2));
+      else write(`dz backlog (dry-run): ${verdict.action.toUpperCase()} — would create ${rec.id}; align ${rec.goalAlignment.toFixed(3)}${rec.goalId !== null ? ` → ${rec.goalId}` : ''}`);
+      return 0;
+    }
+    const ideas = readIdeas(projectRoot);
+    ideas.push(rec);
+    writeIdeas(projectRoot, ideas);
+    const mirror = await mirrorIdeaVector(projectRoot, rec); // best-effort — never blocks capture
+    if (json) write(JSON.stringify({ action: verdict.action, idea: rec, related: verdict.relatedIds, exitCode: 0 }, null, 2));
+    else {
+      write(`dz backlog: ${verdict.action.toUpperCase()} — captured ${rec.id}`);
+      if (rec.goalId !== null) write(`  top goal: ${rec.goalId} (alignment ${rec.goalAlignment.toFixed(3)})`);
+      if (verdict.relatedIds.length > 0) write(`  related: ${verdict.relatedIds.join(', ')}`);
+      write('  proposal: (write your own — dz backlog add --proposal "<text>"; the CLI never fabricates it)');
+      if (mirror.error !== undefined) write(`  ↳ vector mirror deferred: ${mirror.error}`);
+    }
+    return 0;
+  }
+
+  if (sub === 'list') {
+    let ideas = readIdeas(projectRoot);
+    const status = options.get('status');
+    const goal = options.get('goal');
+    if (status !== undefined) ideas = ideas.filter((i) => i.status === (status as IdeaStatus));
+    if (goal !== undefined) ideas = ideas.filter((i) => i.goalId === goal);
+    if (json) {
+      write(JSON.stringify({ ideas, exitCode: 0 }, null, 2));
+      return 0;
+    }
+    if (ideas.length === 0) {
+      write('dz backlog: no ideas' + (status !== undefined || goal !== undefined ? ' match the filter' : ' yet — dz backlog add "<idea>"'));
+      return 0;
+    }
+    write(`dz backlog — ${ideas.length} idea(s)`);
+    for (const i of ideas) write(`  ${i.id}  [${i.status}] e${i.effort} align ${i.goalAlignment.toFixed(2)}${i.goalId !== null ? ` (${i.goalId})` : ''}  ${i.text.slice(0, 70)}`);
+    return 0;
+  }
+
+  if (sub === 'show') {
+    const id = options.get('_positional_1');
+    if (id === undefined) return emitErr('an idea id is required: dz backlog show <id>');
+    const rec = readIdeas(projectRoot).find((i) => i.id === id);
+    if (rec === undefined) return emitErr(`no idea ${id}`);
+    write(json ? JSON.stringify({ idea: rec, exitCode: 0 }, null, 2) : JSON.stringify(rec, null, 2));
+    return 0;
+  }
+
+  if (sub === 'goals') {
+    const goalMap = readGoalMap(projectRoot);
+    if (flags.has('validate')) {
+      const problems: string[] = [];
+      const seen = new Set<string>();
+      for (const g of goalMap.goals) {
+        if (seen.has(g.id)) problems.push(`duplicate goal id: ${g.id}`);
+        seen.add(g.id);
+        if (g.statement.trim() === '') problems.push(`goal ${g.id} has an empty statement`);
+        if (!(g.weight > 0 && g.weight <= 1)) problems.push(`goal ${g.id} weight ${g.weight} is out of (0,1]`);
+      }
+      if (json) write(JSON.stringify({ valid: problems.length === 0, problems, goals: goalMap.goals.length, exitCode: problems.length === 0 ? 0 : 1 }, null, 2));
+      else if (problems.length === 0) write(`dz backlog goals: valid (${goalMap.goals.length} goal(s))`);
+      else { write('dz backlog goals: INVALID'); for (const p of problems) write(`  - ${p}`); }
+      return problems.length === 0 ? 0 : 1;
+    }
+    if (json) {
+      write(JSON.stringify({ goals: goalMap.goals, exitCode: 0 }, null, 2));
+      return 0;
+    }
+    if (goalMap.goals.length === 0) {
+      write('dz backlog goals: no compass — create .dz/backlog/goals.json ({ "version":1, "goals":[{ "id","statement","weight","keywords" }] })');
+      return 0;
+    }
+    write(`dz backlog — ${goalMap.goals.length} goal(s)`);
+    for (const g of goalMap.goals) write(`  ${g.id} (w=${g.weight}): ${g.statement}`);
+    return 0;
+  }
+
+  if (sub === 'roulette') {
+    const ideas = readIdeas(projectRoot);
+    const pool = eligibleIdeas(ideas);
+    if (pool.length === 0) {
+      write(json ? JSON.stringify({ pick: null, eligible: 0, exitCode: 0 }) : 'dz backlog roulette: no eligible ideas (status new/enriched)');
+      return 0;
+    }
+    const now = Date.now();
+    const pickN = options.get('pick');
+    if (pickN !== undefined) {
+      const n = Math.max(1, Math.floor(Number(pickN)) || 1);
+      const ranked = rankRoulette(ideas, cfg.roulette, now).slice(0, n);
+      if (json) write(JSON.stringify({ ranked, exitCode: 0 }, null, 2));
+      else { write(`dz backlog roulette — top ${ranked.length} by weight`); for (const i of ranked) write(`  ${i.id}  align ${i.goalAlignment.toFixed(2)} e${i.effort}  ${i.text.slice(0, 60)}`); }
+      return 0;
+    }
+    const seedOpt = options.get('seed');
+    const seed = seedOpt !== undefined && Number.isFinite(Number(seedOpt)) ? Number(seedOpt) : Math.floor(Math.random() * 2 ** 31);
+    const pick = spinRoulette(ideas, cfg.roulette, seededRng(seed), now)!;
+    let committed = false;
+    if (flags.has('commit')) {
+      const idx = ideas.findIndex((i) => i.id === pick.id);
+      ideas[idx]!.status = 'in-progress';
+      writeIdeas(projectRoot, ideas);
+      committed = true;
+    }
+    if (json) write(JSON.stringify({ pick, seed, committed, exitCode: 0 }, null, 2));
+    else {
+      write(`dz backlog roulette (seed ${seed}): ${pick.id} — ${pick.text.slice(0, 70)}`);
+      write(`  align ${pick.goalAlignment.toFixed(3)}${pick.goalId !== null ? ` (${pick.goalId})` : ''} · effort ${pick.effort}${committed ? ' · → in-progress' : ' · (add --commit to start it)'}`);
+    }
+    return 0;
+  }
+
+  if (sub === 'enrich') {
+    const id = options.get('_positional_1');
+    if (id === undefined) return emitErr('an idea id is required: dz backlog enrich <id>');
+    const ideas = readIdeas(projectRoot);
+    const rec = ideas.find((i) => i.id === id);
+    if (rec === undefined) return emitErr(`no idea ${id}`);
+    const goalMap = readGoalMap(projectRoot);
+    const related = ideas.filter((i) => rec.relatedIds.includes(i.id));
+    const staging = stageEnrichment(projectRoot, rec, related, goalMap);
+    rec.status = 'enriched';
+    rec.enrichedPath = `features/${staging.slug}`;
+    writeIdeas(projectRoot, ideas);
+    if (json) write(JSON.stringify({ slug: staging.slug, scaffoldPath: staging.scaffoldPath, handoff: 'idea2prd-manual', exitCode: 0 }, null, 2));
+    else {
+      write(`dz backlog enrich: staged ${rec.id} → ${staging.scaffoldPath}`);
+      write('  HAND OFF to the idea2prd-manual skill (agent phase) — the CLI stages the input; the agent writes the PRD.');
+      write('  honesty/verification (claim-check, red-team, Brain recall) live at THIS layer, not assumed from idea2prd.');
+    }
+    return 0;
+  }
+
+  if (sub === 'jira') {
+    const id = options.get('_positional_1');
+    if (id === undefined) return emitErr('an idea id is required: dz backlog jira <id>');
+    const ideas = readIdeas(projectRoot);
+    const rec = ideas.find((i) => i.id === id);
+    if (rec === undefined) return emitErr(`no idea ${id}`);
+    const adapter = resolveJiraAdapter(cfg);
+    const draft = buildJiraDraft(rec, readGoalMap(projectRoot));
+    const ref = await adapter.createIssue(draft, makeBacklogIO(projectRoot));
+    rec.jiraKey = ref.key ?? `outbox:${rec.id}`;
+    writeIdeas(projectRoot, ideas);
+    const verify = await adapter.verify();
+    if (json) write(JSON.stringify({ ref, verify, adapter: adapter.backend, exitCode: 0 }, null, 2));
+    else {
+      write(`dz backlog jira: ${adapter.backend} → ${ref.stub ? 'stub' : 'live'} ${ref.key ?? '(no key)'}`);
+      write(`  outbox: ${ref.outboxPath}`);
+      if (!verify.ready) write(`  ⚠ manual wiring: ${verify.instruction}`);
+    }
+    return 0;
+  }
+
+  if (sub === 'harmonize') {
+    const apply = flags.has('apply');
+    const thr = options.get('threshold');
+    const report = await harmonizeBacklog(projectRoot, { apply, ...(thr !== undefined ? { threshold: Number(thr) } : {}) });
+    if (json) {
+      write(JSON.stringify({ ...report, exitCode: 0 }, null, 2));
+      return 0;
+    }
+    write(`dz backlog harmonize (${report.mode}${report.fellBackToExact ? ', exact-text' : ''}): ${report.kept} cluster(s), ${report.dropped} merge-able, ${report.unique} unique (θ ${report.threshold})`);
+    for (const c of report.clusters) write(`  keep ${c.keep} ← ${c.drops.join(', ')}`);
+    if (report.snapshotPath !== undefined) write(`  snapshot: ${report.snapshotPath}`);
+    if (report.pruneError !== undefined) write(`  ⚠ ${report.pruneError} — run dz vector reindex or re-run harmonize when the store is available`);
+    if (!apply && report.dropped > 0) write('  (dry-run — re-run with --apply to merge, after the snapshot)');
+    return 0;
+  }
+
+  // bare / unknown sub — help.
+  write('dz backlog — the Smart Backlog: a goal-directed idea pipeline over the Brain vector engine');
+  write('  add "<idea>" [--effort N][--proposal <t>][--dry-run]   capture (semantic dedup + GoalMap alignment)');
+  write('  list [--status <s>][--goal <id>]                       list ideas');
+  write('  show <id>                                              full record');
+  write('  goals [--validate]                                     the compass (.dz/backlog/goals.json)');
+  write('  roulette [--pick N][--seed n][--commit]                weighted draw for what to work on next');
+  write('  enrich <id>                                            stage the idea2prd hand-off (agent expands)');
+  write(`  jira <id>                                              draft a Jira issue (adapter: ${[...BACKLOG_BACKENDS].join('|')})`);
+  write('  harmonize [--apply][--threshold 0-1]                   batch semantic dedup of the backlog');
+  return sub === undefined ? 0 : 1;
+}
+
 /**
  * `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
@@ -6495,6 +6845,10 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdSkillsVerify(options, flags, cwd, write);
       case 'compounding':
         return cmdCompounding(options, flags, cwd, write);
+      case 'score':
+        return cmdScore(options, flags, cwd, write);
+      case 'backlog':
+        return await cmdBacklog(options, flags, cwd, write);
       case 'routing':
         return cmdRouting(options, flags, cwd, write);
       case 'bto-optimize':