@dzhechkov/harness-cli 0.3.249 → 0.3.250

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.249",
+  "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,7 +41,7 @@
     "sbom.json"
   ],
   "dependencies": {
-    "@dzhechkov/harness-core": "^0.3.140",
+    "@dzhechkov/harness-core": "^0.3.141",
     "@dzhechkov/harness-presets": "^0.5.0",
     "@dzhechkov/scout": "^0.8.0",
     "@dzhechkov/skills-devops": "^0.3.0",

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0a4369c88d48323b3b2ceb18b89ec3a0b6f6f7016778de3ac583f8397531b1b3"
+          "content": "1559995482381fd6ac146e6d229cb7d33476cdca8fad21fd361467dd698bd065"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "e176f74bf8ff0fe938e1bf9b25db392c1adbbd4b7b5b2b63520cb8baa99df82d"
+          "content": "e41e9538474ad80901474841e66f3be8b9f4fdc24f85b4168a13958f19f0762c"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "8bfdc5551ea8d4897f8bb2ab50e374145965e73b4dca8d01325f5388412d804c"
+          "content": "038b4bf4c9295202129662e1caf3b8b139c91f69b2e292373066154b644cc97c"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0ae60f97c9b1b9e7afabcc8aa540eae700950539f5adc511c6f02cbe634775bd"
+          "content": "dafbac9c642da206ddfadb9081f01ef2a4cfba98dee719ef64200241d2b76726"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "207f5a322bb9154eb34478746318abf1f67660f670a92d7bede2fd4a725d4962"
+          "content": "4e22f0553a19181eea750db59bd3eec84fd880473ac523705a1a26197665e87e"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "1d3e6fb9e19aa8fd589487335a8004cc6f7a6af43472b40e31f9139a482f7e85"
+          "content": "9a32862f99d3d0211e08ea49c7091f5697acdd2789ac05137203abd6ed7a9b3e"
         }
       ]
     },
@@ -225,7 +225,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a82b15dd9d166764479528e9f9ede45fc39d1b4068a96f19f158aa5a4c03369b"
+          "content": "2e013ab73b4eb3dd248ed0fbbd5c050911ad667bb78054fde0bb021fbd1815db"
         }
       ]
     },

package/src/cli.ts

@@ -207,7 +207,28 @@ import {
   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';
@@ -240,6 +261,14 @@ Usage:
   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)
@@ -2218,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;
     }
@@ -6149,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
@@ -6581,6 +6847,8 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         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':