@dzhechkov/harness-cli 0.7.3 → 0.7.5

package/src/cli.ts

@@ -7,7 +7,11 @@
 import { appendFileSync, chmodSync, closeSync, cpSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execFileSync, execSync, spawn, spawnSync, type ChildProcess } from 'node:child_process';
+import { request as httpsRequest } from 'node:https';
+import { KNOWN_CLI_FLAGS } from './known-flags.js';
+import { isBooleanFlag } from './boolean-flags.js';
+import { resolveInstallSpec } from './install-spec.js';
+import { execFile, execFileSync, execSync, spawn, spawnSync, type ChildProcess } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import { homedir, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
@@ -318,6 +322,12 @@ import {
   buildRecap,
   renderRecap,
   parseSourceManifest,
+  tgPostHtmlIssues,
+  tgVisibleLength,
+  decideTgSend,
+  TG_TEXT_LIMIT,
+  countRecallEventsForRun,
+  unknownFlagNotice,
   mirrorWriterExplanation,
   appendRecallUsage,
   closenessLine,
@@ -441,8 +451,11 @@ import {
   decideRecordWrite,
   decideReadBack,
   recordVerdictLine,
+  buildCadenceReport,
+  CADENCE_WINDOW_DAYS,
 } from '@dzhechkov/harness-core';
 import type { RecordKind, RecordDecision } from '@dzhechkov/harness-core';
+import type { CadenceWindow } from '@dzhechkov/harness-core';
 import type { MutationEntryResult, MutationObservation, MutationRegistryEntry } from '@dzhechkov/harness-core';
 import type { SkillApplyFailure, SkillLoadFailure } from '@dzhechkov/harness-core';
 import type { ReqeDebt } from '@dzhechkov/harness-core';
@@ -493,6 +506,8 @@ Usage:
   dz epoch-replay --score <judgments.json> --work-order <file> [--slice <name>] [--json]   (un-blind against the pre-registered assignment → SUPPORTED only when the two 95% Wilson CIs are DISJOINT, else FALSIFIED / INCONCLUSIVE)
   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 recap [--day|--week|--month] [--at <ISO date>] [--project <dir>] [--json]   (what was done over a window, from records only: deliveries with the grade an independent review STATED — a report naming two grades is reported ambiguous, never guessed — registry publishes, gate verdicts, knowledge reuse. --quarter/--half-year/--year are RECOGNISED and REFUSED with the real span in days: there is one complete quarter and the longest record is 174 days. Every section carries its own data-start date, and "the source was not read" never prints as zero. Contaminated measures — commit count, lines, tokens, learning-event volume, inventory counts, lesson count — are not computed, and the report says so. exit 0 reported / 2 refused)
+  dz cadence [--window day|week|month|quarter|halfyear|year] [--json]   (the WHAT-SHIPPED aggregator: graded-shipment cadence by ISO week + npm-publish cadence (recap cache) + guard repeat decay on the FIXED rule set + recall reuse; a window deeper than 2× the record is REFUSED with the depth named (ADR: a cadence from one point is scale forgery); exit 0 report / 2 refused-window / 1 usage)
+  dz tg-post --draft <file.html> [--manifest <sources.json>] [--channel <@name|id>] [--send --yes] [--night] [--preview] [--json]   (the sender for an APPROVED channel post, per the accepted genai-tweets-channel ADRs: HTML mode only — never MarkdownV2; link preview OFF by default (x.com previews in Telegram are broken); the 00:00-06:00 MSK quiet window refuses without an explicit --night. DEFAULT IS A DRY-RUN: it validates the draft (tag balance, allowed tags, bare &/<, the 4096 visible-character limit with the overshoot counted) and runs the provenance gate over --manifest IN-PROCESS — a draft with no manifest is refused as unchecked, and anything but ALLOWED refuses. A real send needs --send --yes, stating ADR-004's manual-publishing decision out loud each time. The token comes from TELEGRAM_BOT_TOKEN or telegram.tokenFile in .dz/config.json and is never printed. exit 0 sent or clean dry-run / 1 refused or Telegram error / 2 usage)
   dz name-check [--command <n>] [--module <basename>] [--export <a,b>] [--project <dir>] [--json]   (is this name free, BEFORE a line of code? Scans workspace SOURCE — never dist, because a stale build answers 'free' confidently. Checks a dz command name against the dispatcher AND the help block, a module basename against every package's src/, and exported identifiers against every declaration in the workspace. exit 0 all free / 1 at least one taken, naming where / 2 nothing asked or the scan did not run — an empty sweep is never a clean bill. Honest limit, printed on the passing path: it reads declarations, so a re-export under a different name stays the build's job)
   dz provenance-check --manifest <sources.json> [--project <dir>] [--json]   (nothing goes out citing a source that may not leave this machine. Checks PROVENANCE, not words: every claim names its source, and only a KNOWN kind that resolves safely is cleared. Repo paths go through 'git -C <root> check-ignore' over the RESOLVED path — a symlink into an ignored directory is REFUSED (git classifies the string and never dereferences, MEASURED), and the verdict does not change with your working directory. Store records must be named in the git-TRACKED provenance-public.json, so declaring one public is a reviewable commit rather than a field inside an ignored store. An undeclared kind is refused, never inferred from the path's shape. exit 0 allowed / 1 blocked / 3 NOT ESTABLISHED — an empty manifest, an unreadable one, or an oracle that did not run is never a pass. It proves what was CITED: it cannot see a paraphrase with no citation, nor confidential text pasted by hand into an allowed file)
   dz amendment-check --slug <slug> | --feature-dir <dir> | --all [--json]   (the deterministic Step-8 amendment gate: every AM-N row must resolve to a test found INSIDE the file the row names; the PLAN is authoritative when it carries rows, and an ideation amendment the plan drops is a failure. exit 0 pass/skip, 1 fail, 3 NOT-ESTABLISHED — a section that parsed ZERO rows is never a pass. --all is a CENSUS and always exits 0. Does NOT prove non-vacuity — that is dz discrimination-check)
@@ -639,10 +654,24 @@ function parseArgs(argv: string[]): ParsedArgs {
   const flags = new Set<string>();
   const positional: string[] = [];
 
+  // The command decides `--force`'s arity (valued only under `dz guard`); it is always the first
+  // token when present — a leading `--flag` means there is no command at all.
+  const command = (argv[0] ?? '').startsWith('--') ? '' : argv[0] ?? '';
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index] ?? '';
-    if (arg.startsWith('--')) {
+    // A token that BEGINS with -- but contains whitespace cannot be a flag — no real flag carries a
+    // space (values arrive as separate argv tokens). It is quoted TEXT that happens to open with
+    // dashes: `dz backlog add "--semantic идея…"` was rejected twice with «an idea text is
+    // required» while the text sat right there, eaten as an option (f18fc89e).
+    if (arg.startsWith('--') && !/\s/.test(arg)) {
       const key = arg.slice(2);
+      // A DECLARED boolean flag never swallows the next token (backlog 247ddcfa: `dz sync
+      // --dry-run .` used to disarm the safety flag silently and then WRITE). The declaration is
+      // data with a two-way drift test — see src/boolean-flags.ts.
+      if (isBooleanFlag(key, command)) {
+        flags.add(key);
+        continue;
+      }
       const next = argv[index + 1];
       if (next !== undefined && !next.startsWith('--')) {
         options.set(key, next);
@@ -904,7 +933,15 @@ async function cmdSync(options: Map<string, string>, flags: Set<string>, cwd: st
   // Auto-discover all skills-* packs, or use explicit --canonical
   let canonicalDirs: string[];
   if (canonicalArg !== undefined) {
-    canonicalDirs = [resolve(cwd, canonicalArg)];
+    const dir = resolve(cwd, canonicalArg);
+    if (!existsSync(dir)) {
+      // MEASURED 2026-08-24: a TYPO here used to print `0/0 in sync` and exit 0 — green exactly
+      // when nothing was compared, and in CI that reads as "all skills healthy". An explicit path
+      // that does not exist is an answer about the INVOCATION, not about the skills.
+      write(`dz sync: --canonical ${dir} does not exist — nothing was compared, and nothing-compared is not a clean sync`);
+      return 3;
+    }
+    canonicalDirs = [dir];
   } else {
     const baseDir = join(projectRoot, 'packages', '@dzhechkov');
     canonicalDirs = existsSync(baseDir)
@@ -921,9 +958,20 @@ async function cmdSync(options: Map<string, string>, flags: Set<string>, cwd: st
     force: flags.has('force'),
   });
   const { total, inSync, missing, drift } = report.summary;
+  // The DONE half, beside the SEEN half: a run that wrote its fixes used to print only what it had
+  // seen before writing, and exit 1 — "returns 0 when it did nothing and 1 when it worked". Status
+  // counts describe the tree as found; `wrote` describes what this run changed about it.
+  const wrote = report.skills.filter((skill) => skill.written.length > 0);
   write(
-    `dz sync${report.dryRun ? ' --dry-run' : ''}: ${inSync}/${total} in sync, ${missing} missing, ${drift} drift`,
+    `dz sync${report.dryRun ? ' --dry-run' : ''}: ${inSync}/${total} in sync, ${missing} missing, ${drift} drift${wrote.length > 0 ? ` — wrote ${wrote.length} skill(s)` : ''}`,
   );
+  if (total === 0) {
+    // Nothing was compared. Exit 3, the house not-established convention (`dz workflow-lint`,
+    // `check-plan-completeness`) — never 0: a gate that is green when it never ran is the defect
+    // this repo keeps finding elsewhere (the publish gate, the scout 401, the recall log).
+    write(`dz sync: 0 canonical skill(s) found under ${canonicalDirs.join(', ')} — nothing was compared, and nothing-compared is not a clean sync`);
+    return 3;
+  }
   // Skip-and-collect (D1): the broken canonical skills are NAMED on stderr, and their
   // presence keeps the exit code non-zero — a partial sync is not a clean sync.
   if (report.failures.length > 0) {
@@ -932,7 +980,10 @@ async function cmdSync(options: Map<string, string>, flags: Set<string>, cwd: st
     for (const line of formatSkillLoadFailures(report.failures)) writeErr(line);
     return 1;
   }
-  return missing === 0 && drift === 0 ? 0 : 1;
+  // The exit reflects the OUTCOME: a missing/drift skill this run wrote is resolved, not pending.
+  // A dry run writes nothing, so its exit keeps the CI meaning — 1 whenever work exists.
+  const unresolved = report.skills.filter((skill) => skill.status !== 'in-sync' && skill.written.length === 0);
+  return unresolved.length === 0 ? 0 : 1;
 }
 
 function cmdCreateSkill(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
@@ -1903,6 +1954,32 @@ async function cmdInstall(
     return 1;
   }
 
+  // install-spec-honesty (43a52cf2 + c999786b): resolve the spec to {npmSpec, dirName} BEFORE any
+  // npm process runs — the versioned form used to npm-install SUCCESSFULLY (mutating the project's
+  // package.json) and then die on an invented node_modules path.
+  const specResolution = resolveInstallSpec(pkg, (p) => resolve(cwd, p), {
+    isFile: (p) => { try { return statSync(p).isFile(); } catch { return false; } },
+    isDir: (p) => { try { return statSync(p).isDirectory(); } catch { return false; } },
+    readTarballName: (p) => {
+      try {
+        const out = execSync(`tar -xzOf ${JSON.stringify(p)} package/package.json`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+        const name = (JSON.parse(out) as { name?: unknown }).name;
+        return typeof name === 'string' && name !== '' ? name : null;
+      } catch { return null; }
+    },
+    readDirName: (p) => {
+      try {
+        const name = (JSON.parse(readFileSync(join(p, 'package.json'), 'utf-8')) as { name?: unknown }).name;
+        return typeof name === 'string' && name !== '' ? name : null;
+      } catch { return null; }
+    },
+  });
+  if (specResolution.kind === 'refused') {
+    write(`dz install: ${specResolution.reason}`);
+    write(`  ${specResolution.hint}`);
+    return 1;
+  }
+
   const targetOpt = options.get('target') ?? 'claude-code';
   const targetResolution = resolveTargetName(targetOpt);
   if (targetResolution.kind === 'unknown') {
@@ -1915,8 +1992,8 @@ async function cmdInstall(
   const projectRoot = resolve(cwd, options.get('project') ?? '.');
 
   // Step 1: npm install the package (installRunner is the CliIo test seam — unset in production)
-  write(`Installing ${pkg}...`);
-  const installCmd = `npm install ${pkg} --save-dev --no-fund --no-audit`;
+  write(`Installing ${specResolution.npmSpec}${specResolution.kind === 'name' ? '' : ` (${specResolution.kind} → node_modules/${specResolution.dirName})`}...`);
+  const installCmd = `npm install ${JSON.stringify(specResolution.npmSpec)} --save-dev --no-fund --no-audit`;
   try {
     if (installRunner) installRunner(installCmd, projectRoot);
     else execSync(installCmd, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf-8' });
@@ -1925,8 +2002,9 @@ async function cmdInstall(
     return 1;
   }
 
-  // Step 2: Find SKILL.md files in the installed package
-  const pkgDir = join(projectRoot, 'node_modules', pkg);
+  // Step 2: Find SKILL.md files in the installed package — under the RESOLVED dir name, never the
+  // raw spec (path.join concatenates an absolute segment; a version suffix invents a dir).
+  const pkgDir = join(projectRoot, 'node_modules', specResolution.dirName);
   if (!existsSync(pkgDir)) {
     write(`dz install: package not found at ${pkgDir}`);
     return 1;
@@ -2184,6 +2262,31 @@ function cmdStatuslineInstall(options: Map<string, string>, cwd: string, write:
 function cmdStatuslineFaRecord(options: Map<string, string>, cwd: string, write: Write): number {
   const slug = (options.get('slug') ?? '').trim();
   const step = (options.get('step') ?? '').trim();
+
+  // `--recalled auto` derives the count from the recall-usage log for `--run <id>`, replacing the
+  // pipeline's hardcoded `--recalled 3` (a literal at three call sites — the fallback writer that
+  // lights the panel had nowhere to get a real number until `dz recall` began recording itself).
+  if ((options.get('recalled') ?? '').trim() === 'auto') {
+    const runKey = (options.get('run') ?? '').trim();
+    if (runKey === '') {
+      write('dz statusline --fa-record: --recalled auto needs --run <id> — without a run key there is nothing to count');
+      return 2;
+    }
+    // The COUNT's source and the PANEL's home are two different addresses. The pipeline records
+    // recalls in the canonical BRAIN store while the panel state lives in the project — with a
+    // separate `args.brain` the count read from `--project` would be a silent zero over the wrong
+    // log (the dz sync 0/0 class, again). `--count-project` names the log's home explicitly and
+    // defaults to `--project` for the common single-root case.
+    const countRoot = resolve((options.get('count-project') ?? options.get('project') ?? cwd).trim() || cwd);
+    const derived = countRecallEventsForRun(countRoot, runKey);
+    if (derived === null) {
+      // An unreadable log is not zero. Refusing keeps the panel's PREVIOUS state, which is the
+      // honest outcome: no new claim, rather than a wrong one (the dz sync 0/0 class).
+      write('dz statusline --fa-record: the recall-usage log could not be read — recording nothing rather than a wrong number');
+      return 2;
+    }
+    options.set('recalled', String(derived));
+  }
   if (slug === '' || step === '') {
     write('dz statusline --fa-record: --slug and --step are both required');
     write('  Example: dz statusline --fa-record --slug add-user-auth --step "Step 0" --recalled 5 --stored 2');
@@ -2330,6 +2433,9 @@ function applyUsageCalibrationToConfig(config: Record<string, unknown>, plan: Us
   if (plan.changes.length > 0) {
     usage['calibratedAt'] = plan.after.calibratedAt;
     usage['source'] = plan.after.source;
+    // A fresh calibration re-arms routing for THIS account and clears the legacy free-text switch:
+    // the calibration is the very act the disable-note demanded.
+    usage['calibrationAccount'] = plan.after.calibrationAccount ?? null;
   }
 
   memory['usage'] = usage;
@@ -2519,6 +2625,36 @@ function cmdUsageByStage(
  * non-zero exit. `--project <dir>` scopes ONLY the `.dz/config.json` read/write; measurement is
  * account-wide (all projects).
  */
+function cmdCadence(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const root = resolve(cwd, options.get('project') ?? '.');
+  const windowRaw = (options.get('window') ?? 'week').trim() as CadenceWindow;
+  if (!(windowRaw in CADENCE_WINDOW_DAYS)) {
+    write('dz cadence: --window must be one of ' + Object.keys(CADENCE_WINDOW_DAYS).join('|'));
+    return 1;
+  }
+  const r = buildCadenceReport(root, windowRaw);
+  if (flags.has('json')) { write(JSON.stringify(r)); return r.decision.ok ? 0 : 2; }
+  write('dz cadence — window ' + r.window + ', record depth ' + r.depthDays + ' day(s)');
+  if (!r.decision.ok) {
+    write('  ' + r.decision.reason);
+    if (r.decision.largestAllowed) write('  cure: dz cadence --window ' + r.decision.largestAllowed);
+    return 2;
+  }
+  const weeks = [...new Set([...Object.keys(r.shipments.graded), ...Object.keys(r.npmPublishes.weekly), ...Object.keys(r.recalls.weekly)])].sort();
+  write('  week        shipped(graded)  npm-publishes  recalls');
+  for (const w of weeks) {
+    write('  ' + w.padEnd(12) + String(r.shipments.graded[w] ?? 0).padStart(15) + String(r.npmPublishes.weekly[w] ?? 0).padStart(15) + String(r.recalls.weekly[w] ?? 0).padStart(9));
+  }
+  write('  graded ' + r.shipments.gradedTotal + ' (' + Object.entries(r.shipments.byGrade).sort().map(([g, n]) => g + '×' + n).join(', ') + ') · UNGRADED ' + r.shipments.ungraded + ' (named, not hidden)');
+  if (r.guard.decay.length > 0) {
+    write('  guard repeat decay (FIXED set — rules with pre-window history only):');
+    for (const d of r.guard.decay.slice(0, 8)) write('    ' + d.rule.padEnd(28) + 'before×' + d.before + ' → in-window×' + d.inWindow);
+  }
+  if (r.guard.excludedNewborn.length > 0) write('  excluded newborn rule(s) (no pre-window history — a zero here would be youth, not virtue): ' + r.guard.excludedNewborn.join(', '));
+  for (const dgr of [r.npmPublishes.degraded, r.guard.degraded, r.recalls.degraded]) if (dgr) write('  DEGRADED: ' + dgr);
+  return 0;
+}
+
 function cmdUsage(
   options: Map<string, string>,
   optionLists: Map<string, string[]>,
@@ -2562,6 +2698,8 @@ function cmdUsage(
         weeklyByModel?: typeof u.weeklyByModel;
         estimated: true;
         reqeDue?: number;
+        notEstablished?: readonly string[];
+        estimatesNotForRouting?: { sessionPct: number | null; weeklyPct: number | null };
       } = {
         sessionPct: u.sessionPct,
         weeklyPct: u.weeklyPct,
@@ -2571,6 +2709,10 @@ function cmdUsage(
         limits: limitsPayload,
         estimated: true,
       };
+      // ADR-001 usage-honesty: a consumer that reads null pcts deserves the WHY (closed reason
+      // set), and a human deserves the raw estimates when POLICY (not measurement) nulled them.
+      if (u.notEstablished.length > 0) payload.notEstablished = u.notEstablished;
+      if (u.estimatesNotForRouting !== undefined) payload.estimatesNotForRouting = u.estimatesNotForRouting;
       if (hasModelLimits && u.weeklyByModel !== undefined) payload.weeklyByModel = u.weeklyByModel;
       // re-QE debt surfacing (backlog 6b40e667 — QE #9: the json contract must carry the debt too,
       // a probe is exactly the consumer that needs it). The field appears ONLY when a debt exists,
@@ -2584,6 +2726,22 @@ function cmdUsage(
       );
       return 0;
     }
+    if (u.sessionPct === null && u.weeklyPct === null && u.notEstablished.length > 0) {
+      // Limits may be fully configured and the pcts STILL null — that is the honesty, not a config
+      // gap. Say why, and show the human the raw estimates when only policy nulled them.
+      write('usage: not established — ' + u.notEstablished.join(', '));
+      if (u.estimatesNotForRouting !== undefined) {
+        const e = u.estimatesNotForRouting;
+        write('  estimates (NOT for routing): session ~' + (e.sessionPct ?? '?') + '% · week ~' + (e.weeklyPct ?? '?') + '% — recalibrate on THIS account: dz usage --calibrate --session <pct> --weekly <pct>');
+      } else {
+        write('  the scan established nothing (' + u.sessionTokens + ' session / ' + u.weeklyTokens + ' weekly tokens counted) — a percentage would be a guess, and routing must not eat guesses');
+      }
+      try {
+        const reqe = scanReqeDebts(resolve(cwd, options.get('project') ?? '.'));
+        if (reqe.debts.length > 0) write('re-QE due: ' + reqe.debts.length + ' usage-switched run(s) kept same-family QE — run `dz reqe` for the cross-family pass');
+      } catch { /* advisory only */ }
+      return 0;
+    }
     if (u.sessionPct === null && u.weeklyPct === null) {
       write(
         'usage: unconfigured — set memory.usage.sessionTokenLimit / weeklyTokenLimit in .dz/config.json (percentages are ESTIMATES calibrated from observed exhaustion)',
@@ -3311,10 +3469,34 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
       limit,
       ...(bookFilter !== undefined ? { book: bookFilter } : {}),
     });
-    const { hits, error } = asJson ? await withForeignStdoutOnStderr(runBooks) : await runBooks();
-    if (asJson) { write(JSON.stringify(hits)); return 0; }
+    let booksResult;
+    try {
+      booksResult = asJson ? await withForeignStdoutOnStderr(runBooks) : await runBooks();
+    } catch (err) {
+      // A corrupted store used to surface as a bare top-level `dz: file is not a database` — exit 1
+      // (honest) but with no path and no cure (a2a574a9/c7aec002). Name both.
+      const msg = err instanceof Error ? err.message : String(err);
+      write(`dz recall --books: the book store is unreadable — ${msg}`);
+      write(`  store: ${join(projectRoot, '.dz', 'memory', 'books.sqlite')}`);
+      write('  cure: restore it from a backup, or delete the file and re-digitize (dz brain add --from-slice / book-digitizer) — deleting loses only this project\'s local shelf, the machine-wide brain is separate');
+      return 1;
+    }
+    const { hits, error } = booksResult;
+    // f1451a6a: an EXPLICIT --semantic request whose vector instrument did not run must not read as
+    // a clean 0-hit search. error!==undefined here means the INSTRUMENT failed (embedder/sqlite
+    // unavailable), not that the shelf is empty — house convention exit 3 = not-established.
+    const semanticNotEstablished = flags.has('semantic') && error !== undefined;
+    if (asJson) {
+      if (semanticNotEstablished) { write(JSON.stringify({ hits, notEstablished: error })); return 3; }
+      write(JSON.stringify(hits));
+      return 0;
+    }
     write(`dz recall "${query}" --books${bookFilter !== undefined ? ` --book ${bookFilter}` : ''}  —  ${hits.length} KU hit(s)`);
     if (error !== undefined) write(`  (${error})`);
+    if (semanticNotEstablished) {
+      write('  --semantic was EXPLICIT and the vector instrument did not run — nothing was established (exit 3, not a clean 0)');
+      return 3;
+    }
     for (const h of hits) {
       const src = h.chapter !== undefined ? ` [${h.book} гл.${h.chapter}${h.pages ? ` с.${h.pages[0]}-${h.pages[1]}` : ''}]` : ` [${h.book}]`;
       write(`  (${h.type}) ${h.name}${src}`);
@@ -3430,6 +3612,12 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
     write(JSON.stringify(hits.map((h) => ({
       ...h.pattern,
       relevance: boost === null && 'score' in h && typeof h.score === 'number' ? h.score : null,
+      // The TRUE cosine, as a second companion key — the design named it and the first ship missed
+      // it, so a scripted consumer STILL could not threshold (found while recalibrating the floors:
+      // every probe returned "no similarity" through --json while the human output showed sim=).
+      // Unlike `relevance` it SURVIVES a domain boost: closeness is order-independent (ADR-001 of
+      // recall-true-closeness), and null means "not measured for this hit", never zero.
+      similarity: 'similarity' in h && typeof h.similarity === 'number' ? h.similarity : null,
     }))));
     // The honesty notes go to STDERR here rather than being skipped: the JSON branch
     // used to return before them, so a scripted caller was told nothing about a boost
@@ -3513,9 +3701,13 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
   if (vectorOn && hits.length > 0) {
     const measured = hits.filter((h) => typeof h.similarity === 'number' && Number.isFinite(h.similarity));
     if (measured.length > 0) {
+      const runId = (options.get('run') ?? '').trim();
       appendRecallUsage({
         projectRoot: projectRoot,
         query: shownQuery,
+        // `--run` threads a caller's run key into the log, so a later `--recalled auto` can count
+        // THIS run's events instead of asserting a literal (the /feature-adr panel's `--recalled 3`).
+        ...(runId === '' ? {} : { runId }),
         hits: measured.map((h) => ({ dzId: patternRecordId(h.pattern), score: h.similarity as number })),
       });
     }
@@ -9497,6 +9689,26 @@ function packNpmName(packDir: string): string | undefined {
   }
 }
 
+/**
+ * Parse `pnpm pack --json` STDOUT robustly: a package with a `prepack` script echoes lifecycle
+ * banners first, and the banner text itself may contain '[' or '{' (skills-feature-adr's guard
+ * does) — so candidates are tried from the LAST line-start opener backwards; pnpm's JSON is the
+ * final thing on stdout. MEASURED 2026-08-25: byte-0 parse failed on the banner, first-opener
+ * parse failed on the banner's own array literal.
+ */
+function parsePnpmPackJson(out: string): unknown {
+  const starts: number[] = [];
+  for (let li = 0; li < out.length; li = out.indexOf('\n', li) + 1) {
+    const ch = out[li];
+    if (ch === '{' || ch === '[') starts.push(li);
+    if (out.indexOf('\n', li) === -1) break;
+  }
+  for (let ci = starts.length - 1; ci >= 0; ci--) {
+    try { return JSON.parse(out.slice(starts[ci])); } catch { /* try an earlier candidate */ }
+  }
+  throw new Error('pnpm pack emitted no parseable JSON');
+}
+
 function npmPackedPaths(packDir: string): string[] {
   // `pnpm`, not `npm`: the PUBLISHER is `pnpm publish` (see `publishArgv`), and the two packers do not
   // agree. MEASURED 2026-08-21 on `skills-news`: `npm pack` emits a 1051-byte package.json identical
@@ -9508,7 +9720,7 @@ function npmPackedPaths(packDir: string): string[] {
     encoding: 'utf-8',
     maxBuffer: 64 * 1024 * 1024,
   });
-  const parsed = JSON.parse(out) as { files?: { path: string }[] } | { files?: { path: string }[] }[];
+  const parsed = parsePnpmPackJson(out) as { files?: { path: string }[] } | { files?: { path: string }[] }[];
   const entry = Array.isArray(parsed) ? parsed[0] : parsed;
   const files = entry?.files ?? [];
   return files.map((f) => f.path.replace(/^package\//, '')).sort();
@@ -9538,7 +9750,7 @@ function extractIntoTempDir(packDir: string, tmp: string): { dir: string; cleanu
     encoding: 'utf-8',
     maxBuffer: 64 * 1024 * 1024,
   });
-  const parsed = JSON.parse(out) as { filename?: string } | { filename?: string }[];
+  const parsed = parsePnpmPackJson(out) as { filename?: string } | { filename?: string }[];
   const entry = Array.isArray(parsed) ? parsed[0] : parsed;
   const tgz = entry?.filename;
   if (tgz === undefined) throw new Error(`pnpm pack did not name a tarball for ${packDir}`);
@@ -9670,11 +9882,11 @@ function recapReuse(repo: string, window: RecapWindow): ReuseFacts | null {
 }
 
 /** Publishes come from a cache ONLY. 51 packages cost 18.3s over the network — never inside a report. */
-function recapPublishes(repo: string): { dataStart: string | null; items: Publish[] } | null {
+function recapPublishes(repo: string): { dataStart: string | null; items: Publish[]; fetchedAt?: string; failed?: readonly string[] } | null {
   const path = join(repo, '.dz', 'recap', 'npm-times.json');
   if (!existsSync(path)) return null;
   try {
-    const raw = JSON.parse(readFileSync(path, 'utf-8')) as { packages?: Record<string, { versions?: Record<string, string> }> };
+    const raw = JSON.parse(readFileSync(path, 'utf-8')) as { fetchedAt?: string; failed?: string[]; packages?: Record<string, { versions?: Record<string, string> }> };
     const items: Publish[] = [];
     for (const [pkg, entry] of Object.entries(raw.packages ?? {})) {
       for (const [version, iso] of Object.entries(entry.versions ?? {})) {
@@ -9683,7 +9895,12 @@ function recapPublishes(repo: string): { dataStart: string | null; items: Publis
       }
     }
     const sorted = items.map((i) => i.iso).sort();
-    return { dataStart: sorted.length > 0 ? (sorted[0] as string).slice(0, 10) : null, items };
+    return {
+      dataStart: sorted.length > 0 ? (sorted[0] as string).slice(0, 10) : null,
+      items,
+      ...(typeof raw.fetchedAt === 'string' ? { fetchedAt: raw.fetchedAt } : {}),
+      ...(Array.isArray(raw.failed) && raw.failed.length > 0 ? { failed: raw.failed.filter((f): f is string => typeof f === 'string') } : {}),
+    };
   } catch {
     return null;
   }
@@ -9966,10 +10183,276 @@ function cmdNameCheck(options: Map<string, string>, flags: Set<string>, cwd: str
   return decision.exit;
 }
 
-function cmdRecap(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+// ── recap publish-times cache (feature recap-publish-cache) ──────────────────
+//
+// The Publishes section is the one recap section whose timestamps a third party holds — and the one
+// that was always `unavailable`, because nothing ever filled its cache. The fetch lives HERE, behind
+// an explicit flag, never inside the report: 51 packages cost 18.3s sequentially (measured in the
+// recap design), and a report that does network I/O is a report that fails when the network does.
+
+const RECAP_NPM_CACHE_REL = '.dz/recap/npm-times.json';
+
+interface NpmTimesCache {
+  readonly version: 1;
+  readonly fetchedAt: string;
+  readonly packages: Record<string, { versions: Record<string, string> }>;
+  /** Packages the registry did not answer for. A zero from a failed source is not a measured zero. */
+  readonly failed: readonly string[];
+}
+
+/**
+ * Ask the registry when every non-private workspace package's versions were published.
+ *
+ * Genuinely parallel in batches of 8 (`execFile`, not `spawnSync` — a sync call in a loop stays
+ * sequential whatever the batch size claims, which is exactly the kind of false label this pipeline
+ * keeps removing): measured in the recap design at 5.7s against 18.3s sequential over 51 packages.
+ * A package whose lookup fails lands in `failed`, never silently absent — the same class as the
+ * scout 401 that printed `github: 0` and read as "nothing new exists".
+ */
+async function fetchNpmPublishTimes(repoRoot: string, write: Write): Promise<NpmTimesCache> {
+  const pkgsRoot = join(repoRoot, 'packages', '@dzhechkov');
+  const names: string[] = [];
+  if (existsSync(pkgsRoot)) {
+    for (const e of readdirSync(pkgsRoot, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      const pj = join(pkgsRoot, e.name, 'package.json');
+      if (!existsSync(pj)) continue;
+      try {
+        const meta = JSON.parse(readFileSync(pj, 'utf-8')) as { name?: string; private?: boolean };
+        if (meta.private === true || typeof meta.name !== 'string' || meta.name === '') continue;
+        // Deduplicated: two workspace directories can declare one npm name, and a failure would
+        // then count twice — "2 FAILED" about one distinct package (review round 2).
+        if (!names.includes(meta.name)) names.push(meta.name);
+      } catch { /* an unreadable package.json is not a publishable package */ }
+    }
+  }
+  const packages: Record<string, { versions: Record<string, string> }> = {};
+  const failed: string[] = [];
+  const one = (name: string): Promise<void> => new Promise((done) => {
+    execFile('npm', ['view', name, 'time', '--json'], { timeout: 30_000, maxBuffer: 8 * 1024 * 1024 }, (err: Error | null, stdout: string) => {
+      if (err !== null) { failed.push(name); done(); return; }
+      try {
+        const times = JSON.parse(stdout) as Record<string, string>;
+        const versions: Record<string, string> = {};
+        for (const [k, v] of Object.entries(times)) {
+          if (k === 'created' || k === 'modified' || typeof v !== 'string') continue;
+          versions[k] = v;
+        }
+        // A published package has at least one version by construction — npm will not host an
+        // empty one. Valid-but-empty JSON is therefore an ANOMALY, not a zero: recording it as a
+        // success would let the report read "0 publishes" about a package whose answer was broken
+        // (cross-family review, codex gpt-5.6-sol, 2026-08-24, grade B).
+        if (Object.keys(versions).length === 0) failed.push(name);
+        else packages[name] = { versions };
+      } catch {
+        failed.push(name);
+      }
+      done();
+    });
+  });
+  const BATCH = 8;
+  for (let i = 0; i < names.length; i += BATCH) {
+    await Promise.all(names.slice(i, i + BATCH).map(one));
+    write(`dz recap: registry queried ${Math.min(i + BATCH, names.length)}/${names.length}…`);
+  }
+  // `failed` sorted so the cache is deterministic for a given outcome set.
+  return { version: 1, fetchedAt: new Date().toISOString(), packages, failed: [...failed].sort() };
+}
+
+// ── `dz tg-post` (feature genai-tweets-channel, стадия 0→1) ──────────────────
+//
+// The sender for an APPROVED draft, implementing the channel's own accepted ADRs: HTML mode (never
+// MarkdownV2 — 18 escapes against 3), link preview off by default (x.com previews in Telegram have
+// been broken since 2022), the 00:00-06:00 MSK quiet window, and ADR-004's standing order that
+// publishing stays MANUAL — the default run is a dry-run, and a real send needs --send --yes.
+//
+// The provenance gate runs IN-PROCESS before any send: the draft's sources.json goes through the
+// same classification `dz provenance-check` uses, and anything but ALLOWED refuses. A draft with no
+// manifest is refused too — unchecked is not approved.
+
+function tgReadToken(repoRoot: string, write: Write): string | null {
+  // Token sources, in order: env, then a tokenFile named in .dz/config.json. The token itself is
+  // NEVER printed, logged, or included in any error — only where it was looked for.
+  const env = process.env['TELEGRAM_BOT_TOKEN'];
+  if (env !== undefined && env.trim() !== '') return env.trim();
+  try {
+    const cfg = JSON.parse(readFileSync(join(repoRoot, '.dz', 'config.json'), 'utf-8')) as { telegram?: { tokenFile?: string } };
+    const file = cfg.telegram?.tokenFile;
+    if (typeof file === 'string' && file.trim() !== '' && existsSync(file)) {
+      const text = readFileSync(file, 'utf-8');
+      const m = /TELEGRAM_BOT_TOKEN\s*=\s*"?([^"\n]+)"?/.exec(text);
+      if (m?.[1] !== undefined) return m[1].trim();
+      const bare = text.trim();
+      if (bare !== '' && !bare.includes('\n')) return bare;
+    }
+  } catch { /* fall through to the honest null */ }
+  write('dz tg-post: no bot token — set TELEGRAM_BOT_TOKEN or telegram.tokenFile in .dz/config.json');
+  return null;
+}
+
+function tgApi(token: string, method: string, body: Record<string, unknown>): Promise<{ ok: boolean; description?: string; messageId?: number }> {
+  return new Promise((done) => {
+    const payload = JSON.stringify(body);
+    const req = httpsRequest({
+      hostname: 'api.telegram.org',
+      path: `/bot${token}/${method}`,
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) },
+      timeout: 30_000,
+    }, (res) => {
+      let data = '';
+      res.on('data', (c: Buffer) => { data += c.toString('utf-8'); });
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data) as { ok?: boolean; description?: string; result?: { message_id?: number } };
+          done({ ok: parsed.ok === true, ...(typeof parsed.description === 'string' ? { description: parsed.description } : {}), ...(typeof parsed.result?.message_id === 'number' ? { messageId: parsed.result.message_id } : {}) });
+        } catch {
+          done({ ok: false, description: `unparseable response (HTTP ${res.statusCode ?? '?'})` });
+        }
+      });
+    });
+    req.on('error', (e: Error) => done({ ok: false, description: e.message }));
+    req.on('timeout', () => { req.destroy(); done({ ok: false, description: 'timeout after 30s' }); });
+    req.write(payload);
+    req.end();
+  });
+}
+
+async function cmdTgPost(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
+  const repoRoot = resolve(options.get('project') ?? cwd);
+  const json = flags.has('json');
+  const draftPath = (options.get('draft') ?? '').trim();
+  if (draftPath === '') { write('dz tg-post: --draft <file.html> is required'); return 2; }
+  let draft: string;
+  try {
+    draft = readFileSync(resolve(cwd, draftPath), 'utf-8');
+  } catch {
+    write(`dz tg-post: cannot read draft ${draftPath}`);
+    return 2;
+  }
+
+  const issues = tgPostHtmlIssues(draft);
+
+  // Provenance, in-process. `--manifest` names the draft's sources; its absence is a refusal at the
+  // decision layer, not a quiet pass here.
+  let provenanceOutcome: 'allowed' | 'blocked' | 'not-established' | 'skipped' = 'skipped';
+  const manifestPath = (options.get('manifest') ?? '').trim();
+  if (manifestPath !== '') {
+    let manifest: ReturnType<typeof parseSourceManifest> = null;
+    try { manifest = parseSourceManifest(readFileSync(resolve(cwd, manifestPath), 'utf-8')); } catch { manifest = null; }
+    const publicRecords = new Set<string>();
+    const show = spawnSync('git', ['-C', repoRoot, 'show', `HEAD:${PROVENANCE_PUBLIC_REL}`], { encoding: 'utf-8', maxBuffer: 8 * 1024 * 1024 });
+    if (show.error === undefined && show.status === 0) {
+      try {
+        const raw = JSON.parse(show.stdout ?? '') as { records?: unknown };
+        if (Array.isArray(raw.records)) for (const r of raw.records) if (typeof r === 'string') publicRecords.add(r);
+      } catch { /* an unparseable committed list clears nothing */ }
+    }
+    const resolved = new Map<string, string | null>();
+    const toAsk: string[] = [];
+    for (const c of manifest?.claims ?? []) {
+      if (c.kind !== 'path' || typeof c.source !== 'string' || c.source.trim() === '') continue;
+      const src = c.source.trim();
+      if (resolved.has(src)) continue;
+      const real = provenanceResolve(repoRoot, src);
+      resolved.set(src, real);
+      if (real !== null) toAsk.push(real);
+    }
+    const tracked = new Set<string>();
+    const dirty = new Set<string>();
+    if (toAsk.length > 0) {
+      const ls = spawnSync('git', ['-C', repoRoot, 'ls-files', '-z', '--', ...toAsk], { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 });
+      if (ls.error === undefined && ls.status === 0) {
+        for (const rel of (ls.stdout ?? '').split('\0')) if (rel !== '') tracked.add(resolve(repoRoot, rel));
+      }
+      const onDisk = spawnSync('git', ['-C', repoRoot, 'hash-object', '--no-filters', '--', ...toAsk], { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 });
+      const inHead = spawnSync('git', ['-C', repoRoot, 'ls-tree', '-z', 'HEAD', '--', ...toAsk], { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 });
+      if (onDisk.error !== undefined || onDisk.status !== 0 || inHead.error !== undefined || inHead.status !== 0) {
+        for (const p of toAsk) dirty.add(p);
+      } else {
+        const diskHashes = (onDisk.stdout ?? '').split('\n').map((l: string) => l.trim()).filter((l: string) => l !== '');
+        const headHash = new Map<string, string>();
+        for (const rec of (inHead.stdout ?? '').split('\0')) {
+          if (rec === '') continue;
+          const tab = rec.indexOf('\t');
+          if (tab < 0) continue;
+          const parts = rec.slice(0, tab).split(/\s+/);
+          headHash.set(resolve(repoRoot, rec.slice(tab + 1)), parts[2] ?? '');
+        }
+        toAsk.forEach((abs, i) => {
+          const committed = headHash.get(abs);
+          if (committed === undefined || committed !== diskHashes[i]) dirty.add(abs);
+        });
+      }
+    }
+    const decision = decideSourceProvenance(manifest, {
+      ignoredPaths: provenanceIgnored(repoRoot, toAsk),
+      publicRecords,
+      resolved,
+      trackedPaths: tracked,
+      dirtyPaths: dirty,
+    });
+    provenanceOutcome = decision.outcome;
+    if (!json) for (const line of renderSourceProvenance(decision)) write(line);
+  }
+
+  const decision = decideTgSend({
+    issues,
+    provenanceOutcome,
+    confirmed: flags.has('send') && flags.has('yes'),
+    nowUtcIso: new Date().toISOString(),
+    nightOverride: flags.has('night'),
+  });
+
+  const visible = tgVisibleLength(draft);
+  if (!json) {
+    for (const i of issues) write(`  [${i.kind}] ${i.detail}`);
+    write(`dz tg-post: ${decision.action === 'send' ? 'SENDING' : 'DRY-RUN / REFUSED'} — ${decision.reason}`);
+    write(`  ${visible} visible character(s) of ${TG_TEXT_LIMIT}; provenance: ${provenanceOutcome}`);
+  }
+
+  if (decision.action !== 'send') {
+    if (json) write(JSON.stringify({ ok: false, action: decision.action, reason: decision.reason, issues, visible, provenance: provenanceOutcome }));
+    // A refused send exits 1; a clean DRY-RUN (no --send asked) exits 0 — asking to see is not a failure.
+    return flags.has('send') ? 1 : issues.length > 0 ? 1 : 0;
+  }
+
+  const token = tgReadToken(repoRoot, write);
+  if (token === null) return 2;
+  const channel = (options.get('channel') ?? '').trim();
+  if (channel === '') { write('dz tg-post: --channel @name (or a chat id) is required to send'); return 2; }
+
+  const sent = await tgApi(token, 'sendMessage', {
+    chat_id: channel,
+    text: draft,
+    parse_mode: 'HTML',
+    // ADR-004: x.com previews in Telegram are broken — never rely on them.
+    link_preview_options: { is_disabled: !flags.has('preview') },
+  });
+  if (!sent.ok) {
+    write(`dz tg-post: Telegram refused — ${sent.description ?? 'no description'}`);
+    if (json) write(JSON.stringify({ ok: false, action: 'send', reason: sent.description ?? 'refused', visible }));
+    return 1;
+  }
+  write(`dz tg-post: sent to ${channel}${sent.messageId !== undefined ? ` (message ${sent.messageId})` : ''}`);
+  if (json) write(JSON.stringify({ ok: true, action: 'send', channel, messageId: sent.messageId ?? null, visible }));
+  return 0;
+}
+
+async function cmdRecap(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): Promise<number> {
   const repo = resolve(options.get('project') ?? cwd);
   const json = flags.has('json');
 
+  if (flags.has('refresh-publishes')) {
+    const cache = await fetchNpmPublishTimes(repo, json ? () => {} : write);
+    const cachePath = join(repo, ...RECAP_NPM_CACHE_REL.split('/'));
+    mkdirSync(dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, `${JSON.stringify(cache, null, 2)}\n`);
+    if (!json) {
+      write(`dz recap: publish-times cache written — ${Object.keys(cache.packages).length} package(s)${cache.failed.length > 0 ? `, ${cache.failed.length} FAILED: ${cache.failed.join(', ')}` : ''}`);
+    }
+  }
+
   // Every horizon is RECOGNISED, including the refused ones — swallowing `--year` silently would be
   // the same defect as a gate that passes because it never ran.
   const asked = (['day', 'week', 'month', ...REFUSED_HORIZONS] as const).filter((h) => flags.has(h));
@@ -10001,8 +10484,21 @@ function cmdRecap(options: Map<string, string>, flags: Set<string>, cwd: string,
     reuse: recapReuse(repo, window),
     uncommittedSlugs: deliveries.uncommitted.sort(),
   });
-  if (json) write(JSON.stringify(report));
-  else for (const line of renderRecap(report)) write(line);
+  if (json) {
+    write(JSON.stringify({ ...report, publishesMeta: publishes === null ? null : { fetchedAt: publishes.fetchedAt ?? null, failed: publishes.failed ?? [] } }));
+  } else {
+    for (const line of renderRecap(report)) write(line);
+    // The cache's AGE and its failures print beside the numbers they qualify: third-party
+    // timestamps are only as fresh as the last explicit --refresh-publishes, and a package the
+    // registry did not answer for is MISSING from the section above — said, not implied.
+    if (publishes?.fetchedAt !== undefined) {
+      const days = Math.floor((Date.parse(`${at.slice(0, 10)}T00:00:00Z`) - Date.parse(publishes.fetchedAt)) / 86_400_000);
+      write(`  ℹ publish-times cache fetched ${publishes.fetchedAt.slice(0, 10)}${Number.isFinite(days) && days > 0 ? ` — ${days} day(s) before this report's anchor` : ''}; refresh with --refresh-publishes`);
+    }
+    if (publishes?.failed !== undefined) {
+      write(`  ⚠ the registry did not answer for ${publishes.failed.length} package(s) at the last refresh: ${publishes.failed.join(', ')} — their publishes are MISSING above, not zero`);
+    }
+  }
   return 0;
 }
 
@@ -12865,6 +13361,16 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
   };
   const { command, options, optionLists, flags } = parseArgs(argv);
 
+  // An unrecognised `--flag` must not pass in silence. MEASURED 2026-08-24: `dz recall "x" --breif
+  // --limit 2` printed the full ordinary output and exited 0, so a typo read as "the mode worked".
+  // It WARNS rather than refuses, and the reason is measured, not cautious: 53 of the names this CLI
+  // reads appear nowhere in help, and static extraction over the dispatch table lost `--week` from
+  // `dz recap` — a refusal built on either list would reject working commands, which is a worse
+  // failure than the one being fixed. Goes to STDERR so a `--json` consumer's stdout stays clean.
+  for (const notice of unknownFlagNotice([...flags, ...options.keys()].filter((k) => !k.startsWith('_positional_')), KNOWN_CLI_FLAGS)) {
+    writeErr(notice.line);
+  }
+
   // ── `dz --version` / `dz -v` / `dz version` — PRE-DISPATCH, before the help branch ──
   //
   // Until now `dz --version` printed the whole USAGE manual and exited 0 (MEASURED 2026-08-17,
@@ -13017,6 +13523,10 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         return cmdScore(options, flags, cwd, write);
       case 'recap':
         return cmdRecap(options, flags, cwd, write);
+      case 'cadence':
+        return cmdCadence(options, flags, cwd, write);
+      case 'tg-post':
+        return cmdTgPost(options, flags, cwd, write);
       case 'name-check':
         return cmdNameCheck(options, flags, cwd, write);
       case 'provenance-check':