@dzhechkov/harness-cli 0.3.250 → 0.3.252

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.3.250",
+  "version": "0.3.252",
   "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.141",
+    "@dzhechkov/harness-core": "^0.3.143",
     "@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": "1559995482381fd6ac146e6d229cb7d33476cdca8fad21fd361467dd698bd065"
+          "content": "ff1b1a2239a254f500c999c5c25ab9303561b433fb1cac420a2b28a7bd0d9fd6"
         }
       ]
     },
@@ -105,7 +105,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "e41e9538474ad80901474841e66f3be8b9f4fdc24f85b4168a13958f19f0762c"
+          "content": "c9b415287eda0a7c2ad32dbb7cfc3ecce19aa3b90c96d3fbeedd62d20fe34bc7"
         }
       ]
     },
@@ -115,7 +115,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "038b4bf4c9295202129662e1caf3b8b139c91f69b2e292373066154b644cc97c"
+          "content": "56b4da2639c1721180387f28166d84d065718a4002f556307a6598570d335809"
         }
       ]
     },
@@ -125,7 +125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "dafbac9c642da206ddfadb9081f01ef2a4cfba98dee719ef64200241d2b76726"
+          "content": "4a172ba5384c9716fa48570979b7ffba969599ed5c639d7e7268a829d2b9b4e1"
         }
       ]
     },
@@ -185,7 +185,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4e22f0553a19181eea750db59bd3eec84fd880473ac523705a1a26197665e87e"
+          "content": "65e245ef567ccecdc382bb040f27dd98e01ce2c3a104935aa2dc0558b22220e2"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "9a32862f99d3d0211e08ea49c7091f5697acdd2789ac05137203abd6ed7a9b3e"
+          "content": "1aceceef391cac55d00f7872632d28c4116a82025b9235343b81398fc515f944"
         }
       ]
     },
@@ -225,7 +225,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "2e013ab73b4eb3dd248ed0fbbd5c050911ad667bb78054fde0bb021fbd1815db"
+          "content": "7d6ba26ec1188db3b3ac89f50b015ba1f0c6117b5c30d99b22da41da10c96c12"
         }
       ]
     },

package/src/cli.ts

@@ -117,6 +117,7 @@ import {
   auditRecord,
   guardExitCode,
   DEFAULT_RULES,
+  parsePnpmLockImporters,
   decideProvenance,
   isInsideTree,
   signManifest,
@@ -214,6 +215,10 @@ import {
   ideaId,
   dedupIdea,
   readGoalMap,
+  readGoalMapDetailed,
+  parseEffort,
+  ensureBacklogGitignored,
+  isSafeId,
   alignIdea,
   mirrorIdeaVector,
   snapshotIdeas,
@@ -4855,11 +4860,17 @@ function gatherGuardFacts(op: string, root: string, text: string | undefined, st
     // a resolvable workspace dep becomes its real semver (safe → the rule passes); an UNRESOLVABLE one (points at
     // no workspace package, or not a pnpm workspace) stays `workspace:*` so the rule catches a dep that WOULD ship
     // raw. That is the genuinely dangerous case the rule exists for.
-    const manifests: { name?: string; version?: string; private?: boolean; dependencies?: Record<string, string> }[] = [];
+    type Manifest = { name?: string; version?: string; private?: boolean; dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+    const manifests: Manifest[] = [];
+    const located: { dir: string; m: Manifest }[] = [];
     try {
       const out = execSync('git ls-files "packages/@dzhechkov/*/package.json"', { cwd: root, encoding: 'utf-8' });
       for (const rel of out.split('\n').map((s) => s.trim()).filter(Boolean)) {
-        try { manifests.push(JSON.parse(readFileSync(join(root, rel), 'utf8')) as typeof manifests[number]); } catch { /* skip unreadable */ }
+        try {
+          const m = JSON.parse(readFileSync(join(root, rel), 'utf8')) as Manifest;
+          manifests.push(m);
+          located.push({ dir: rel.replace(/\/package\.json$/, ''), m });
+        } catch { /* skip unreadable */ }
       }
     } catch { /* not a git repo */ }
     const versionByName = new Map<string, string>();
@@ -4909,6 +4920,28 @@ function gatherGuardFacts(op: string, root: string, text: string | undefined, st
       }
       facts['skillPacks'] = skillPacks;
     } catch { /* unreadable packages dir — rule reports nothing rather than inventing a violation */ }
+
+    // lockfile-in-sync: the ERR_PNPM_OUTDATED_LOCKFILE class — a @dzhechkov/* dep spec bumped in a
+    // package.json while pnpm-lock.yaml still records the old specifier. FAIL-OPEN by construction: an
+    // unreadable/unparseable lockfile yields `{parsed:false}` and the rule reports NOTHING.
+    try {
+      const lockText = readFileSync(join(root, 'pnpm-lock.yaml'), 'utf8');
+      const importers = parsePnpmLockImporters(lockText);
+      if (importers === undefined) {
+        facts['lockfile'] = { parsed: false };
+      } else {
+        const rows = located
+          .map(({ dir, m }) => {
+            const declared: Record<string, string> = {};
+            for (const [dep, spec] of Object.entries({ ...(m.dependencies ?? {}), ...(m.devDependencies ?? {}) })) {
+              if (dep.startsWith('@dzhechkov/') && typeof spec === 'string') declared[dep] = spec;
+            }
+            return { importer: dir, declared, locked: importers[dir] };
+          })
+          .filter((r) => Object.keys(r.declared).length > 0);
+        facts['lockfile'] = { parsed: true, importers: rows };
+      }
+    } catch { facts['lockfile'] = { parsed: false }; /* no lockfile (not a pnpm workspace) — rule stays silent */ }
   }
   if (op === 'consolidate') {
     try { facts['drift'] = sweepSkillDrift(root, { scope: 'packages', allowlist: readDriftAllowlist(root) }).drifted.map((d) => d.name); } catch { /* skip */ }
@@ -6199,9 +6232,18 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
   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);
+    // The clamp is ECHOED, never silent (idea 86096d6d): `--effort 13` used to store 5 and say nothing.
+    const eff = parseEffort(options.get('effort'), cfg.roulette.defaultEffort);
+    if (eff.adjusted && !json && eff.note !== undefined) write(`dz backlog: ${eff.note}`);
     const dryRun = flags.has('dry-run');
     const verdict = await dedupIdea(projectRoot, text, cfg);
+    // The TOP-MATCH pair (id @ cosine) is the ADR-002 calibration surface (idea ce914ac2) — observational
+    // only: the band itself is unchanged, but a RELATED verdict now shows WHICH idea produced the cosine.
+    // A negative cosine is a VALID observation (anti-correlated embedding) — only non-finite is absent
+    // (Codex re-QE LOW: `>= 0` suppressed a legitimate negative top match).
+    const topMatch = verdict.topMatchId !== undefined && Number.isFinite(verdict.cosine)
+      ? { id: verdict.topMatchId, cosine: verdict.cosine }
+      : undefined;
     if (verdict.action === 'duplicate') {
       // DUPLICATE ⇒ snapshot + reinforce the existing root; NO new record (ADR-002 T-002b).
       const ideas = readIdeas(projectRoot);
@@ -6212,8 +6254,11 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
         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`);
+      if (json) write(JSON.stringify({ action: 'duplicate', matchedId: verdict.matchedId, cosine: verdict.cosine, ...(topMatch !== undefined ? { topMatch } : {}), ...(eff.note !== undefined ? { effortNote: eff.note } : {}), 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`);
+        if (topMatch !== undefined) write(`  top match ${topMatch.id} @ cosine ${topMatch.cosine.toFixed(3)} (DUPLICATE band ≥ ${cfg.dedup.duplicateThreshold})`);
+      }
       return 0;
     }
     const goalMap = readGoalMap(projectRoot);
@@ -6224,7 +6269,7 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
       text,
       status: 'new',
       createdTs,
-      effort: Number.isFinite(effort) ? Math.max(1, Math.min(5, Math.floor(effort))) : cfg.roulette.defaultEffort,
+      effort: eff.effort,
       goalId: align.goalId,
       goalAlignment: align.goalAlignment,
       relatedIds: [...verdict.relatedIds],
@@ -6234,19 +6279,39 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
     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}` : ''}`);
+      if (json) write(JSON.stringify({ action: verdict.action, dryRun: true, idea: rec, ...(topMatch !== undefined ? { topMatch } : {}), ...(eff.note !== undefined ? { effortNote: eff.note } : {}), 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}` : ''}`);
+        // The calibration surface belongs on the dry-run too (QE LOW-8) — a dry-run is exactly where a
+        // user checks whether a near-duplicate should have crossed the band.
+        if (topMatch !== undefined) write(`  top match ${topMatch.id} @ cosine ${topMatch.cosine.toFixed(3)} (DUPLICATE band ≥ ${cfg.dedup.duplicateThreshold})`);
+      }
       return 0;
     }
+    // Privacy scaffold (idea ec4cd60d): the store we are about to create holds raw prompt-class ideas —
+    // ensure `.dz/backlog/` is gitignored BEFORE the first write. No-op once covered.
+    const ignore = ensureBacklogGitignored(projectRoot);
     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));
+    if (json) write(JSON.stringify({ action: verdict.action, idea: rec, related: verdict.relatedIds, ...(topMatch !== undefined ? { topMatch } : {}), ...(eff.note !== undefined ? { effortNote: eff.note } : {}), gitignore: ignore, exitCode: 0 }, null, 2));
     else {
       write(`dz backlog: ${verdict.action.toUpperCase()} — captured ${rec.id}`);
+      if (verdict.action === 'related' && topMatch !== undefined) {
+        write(`  top match ${topMatch.id} @ cosine ${topMatch.cosine.toFixed(3)} (DUPLICATE band ≥ ${cfg.dedup.duplicateThreshold})`);
+      }
       if (rec.goalId !== null) write(`  top goal: ${rec.goalId} (alignment ${rec.goalAlignment.toFixed(3)})`);
       if (verdict.relatedIds.length > 0) write(`  related: ${verdict.relatedIds.join(', ')}`);
+      if (ignore.action === 'created' || ignore.action === 'appended') {
+        write(`  privacy: ${ignore.action} \`.dz/backlog/\` in ${ignore.path} (ideas are private prompt-class content)`);
+      } else if (ignore.action === 'skipped') {
+        // A privacy scaffold that FAILED must never be silent (QE MED-5): the store now holds raw ideas
+        // that git can see, and only the user can fix it.
+        write(`  ⚠ privacy: could NOT gitignore \`.dz/backlog/\` (${ignore.reason ?? 'unknown error'}) — your ideas are visible to git; add \`.dz/backlog/\` to ${ignore.path} yourself`);
+      } else if (ignore.action === 'user-opted-out') {
+        write('  privacy: `.dz/backlog/` is explicitly un-ignored (a `!` negation in .gitignore) — respecting that; ideas WILL be tracked by git');
+      }
       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}`);
     }
@@ -6282,21 +6347,42 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
   }
 
   if (sub === 'goals') {
-    const goalMap = readGoalMap(projectRoot);
     if (flags.has('validate')) {
+      // A vacuous "valid (0 goal(s))" HID the user's mistake (idea 960c9f26): the defensive reader silently
+      // dropped every malformed entry (e.g. `text` where `statement` belongs). Validate reads the DETAILED
+      // view, warns per dropped entry, and refuses to call a fully-dropped compass valid.
+      const detail = readGoalMapDetailed(projectRoot);
+      const goalMap = detail.goalMap;
       const problems: string[] = [];
+      const warnings: string[] = [];
+      if (detail.parseError !== undefined) problems.push(detail.parseError);
+      for (const d of detail.dropped) warnings.push(`goal[${d.index}]: ${d.reason} — dropped`);
+      // The reader CLAMPS a bad weight before any validation could see it, so validating the clamped
+      // value can only ever pass (QE MED-7 — the branch below was dead code). Warn from the RAW value
+      // the user wrote, and say which value the runtime is actually using.
+      for (const r of detail.repaired) warnings.push(`goal[${r.index}] (${r.id}): ${r.reason} — using ${r.used}`);
       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`);
+        // Defence in depth: the reader guarantees the clamp, so this can only fire if that ever regresses.
         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;
+      // A compass whose entries were ALL dropped is a user error, not an empty compass.
+      const allDropped = detail.present > 0 && goalMap.goals.length === 0;
+      if (allDropped) problems.push(`all ${detail.present} goal entr${detail.present === 1 ? 'y was' : 'ies were'} dropped as malformed — the compass is EMPTY, not valid`);
+      const valid = problems.length === 0;
+      if (json) {
+        write(JSON.stringify({ valid, problems, warnings, dropped: detail.dropped, repaired: detail.repaired, goals: goalMap.goals.length, present: detail.present, exitCode: valid ? 0 : 1 }, null, 2));
+      } else {
+        for (const w of warnings) write(`dz backlog goals: WARNING ${w}`);
+        if (valid) write(`dz backlog goals: valid (${goalMap.goals.length} goal(s)${detail.dropped.length > 0 ? `, ${detail.dropped.length} dropped` : ''})`);
+        else { write('dz backlog goals: INVALID'); for (const p of problems) write(`  - ${p}`); }
+      }
+      return valid ? 0 : 1;
     }
+    const goalMap = readGoalMap(projectRoot);
     if (json) {
       write(JSON.stringify({ goals: goalMap.goals, exitCode: 0 }, null, 2));
       return 0;
@@ -6313,7 +6399,37 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
   if (sub === 'roulette') {
     const ideas = readIdeas(projectRoot);
     const pool = eligibleIdeas(ideas);
-    if (pool.length === 0) {
+    // ── Commit-argument validation runs BEFORE any early return (QE HIGH-2): an empty eligible pool
+    // used to return 0 first, so `--commit <garbage>` reported success having validated nothing. A
+    // mutation request is answered on its own merits, whatever the pool looks like.
+    // parseArgs turns `--commit <id>` into an OPTION and a bare `--commit` into a FLAG. A trailing
+    // positional id is only a commit target when --commit was actually passed (QE HIGH-1): a bare
+    // `dz backlog roulette <id>` must never mutate.
+    const positionalId = options.get('_positional_1');
+    const commitOpt = options.get('commit');
+    const wantsCommit = flags.has('commit') || commitOpt !== undefined;
+    if (!wantsCommit && positionalId !== undefined) {
+      return emitErr(`an idea id alone does not start it — a spin never mutates. Use: dz backlog roulette --commit ${positionalId}`);
+    }
+    const commitId = wantsCommit ? commitOpt ?? positionalId : undefined;
+    if (wantsCommit && commitId !== undefined) {
+      if (!isSafeId(commitId)) return emitErr(`refusing an unsafe idea id: ${JSON.stringify(commitId)}`);
+      const target = ideas.find((i) => i.id === commitId);
+      if (target === undefined) return emitErr(`no idea ${commitId} — run dz backlog list to see the ids`);
+      // TERMINAL ideas must not be silently resurrected (Codex re-QE). in-progress is allowed —
+      // re-committing it is an idempotent no-op, not a resurrection.
+      if (target.status === 'shipped' || target.status === 'dropped') {
+        return emitErr(`idea ${commitId} is ${target.status} — a terminal idea cannot be (re)started`);
+      }
+    }
+    // `--pick N` is a read-only ranking view; combining it with a mutation request is ambiguous and was
+    // silently ignoring the commit (Codex re-QE) — refuse the combination explicitly.
+    if (wantsCommit && options.get('pick') !== undefined) {
+      return emitErr('--pick cannot be combined with --commit — commit a single explicit id without --pick');
+    }
+    if (pool.length === 0 && commitId === undefined) {
+      // A bare `--commit` with nothing to spin cannot name a pick to paste, so it says exactly that.
+      if (wantsCommit) return emitErr('roulette --commit requires an idea id, and there is no eligible idea to suggest one — run dz backlog list');
       write(json ? JSON.stringify({ pick: null, eligible: 0, exitCode: 0 }) : 'dz backlog roulette: no eligible ideas (status new/enriched)');
       return 0;
     }
@@ -6328,18 +6444,31 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
     }
     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)!;
+    // With an empty pool but a valid --commit id, there is nothing to spin — the commit still stands.
+    const spun = pool.length > 0 ? spinRoulette(ideas, cfg.roulette, seededRng(seed), now) : undefined;
+    if (wantsCommit && commitId === undefined) {
+      // --commit takes an EXPLICIT id (idea 5fcd9a2d): the spin is a function of the CURRENT pool, so a
+      // bare `--commit` after the pool changed could start a DIFFERENT idea than the dry-run showed. The
+      // id the user saw is the id that gets committed — the spin no longer decides a mutation.
+      const msg = `roulette --commit requires the idea id you are committing to: dz backlog roulette --commit ${spun!.id} (this spin's pick) — a bare --commit could start a different idea than the one you were shown`;
+      if (json) write(JSON.stringify({ error: msg, pickId: spun!.id, exitCode: 1 }, null, 2));
+      else write(`dz backlog: ${msg}`);
+      return 1;
+    }
+    let pick = spun;
     let committed = false;
-    if (flags.has('commit')) {
-      const idx = ideas.findIndex((i) => i.id === pick.id);
+    if (commitId !== undefined) {
+      // Validated above (safe id + known id) BEFORE any early return.
+      const idx = ideas.findIndex((i) => i.id === commitId);
       ideas[idx]!.status = 'in-progress';
       writeIdeas(projectRoot, ideas);
+      pick = ideas[idx]!;
       committed = true;
     }
-    if (json) write(JSON.stringify({ pick, seed, committed, exitCode: 0 }, null, 2));
-    else {
+    if (json) write(JSON.stringify({ pick: pick ?? null, seed, committed, exitCode: 0 }, null, 2));
+    else if (pick !== undefined) {
       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)'}`);
+      write(`  align ${pick.goalAlignment.toFixed(3)}${pick.goalId !== null ? ` (${pick.goalId})` : ''} · effort ${pick.effort}${committed ? ' · → in-progress' : ` · (start it with: dz backlog roulette --commit ${pick.id})`}`);
     }
     return 0;
   }
@@ -6408,7 +6537,7 @@ async function cmdBacklog(options: Map<string, string>, flags: Set<string>, cwd:
   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('  roulette [--pick N][--seed n][--commit <id>]           weighted draw; --commit takes the id you saw');
   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');