@dzhechkov/harness-cli 0.6.1 → 0.7.0

package/src/cli.ts

@@ -33,6 +33,7 @@ import {
   RECONCILE_BANNER,
   buildRegistry,
   discoverSkillPackDirs,
+  discoverVerifiablePackDirs,
   checkUpstream,
   compareSkills,
   checkAllUpstream,
@@ -155,6 +156,7 @@ import {
   bundleSkills,
   brainHome,
   listBrain,
+  bookKbPath,
   promoteProjectToBrain,
   updateBrainSource,
   queryBrain,
@@ -408,6 +410,8 @@ import {
   amendmentVerdictLine,
   amendmentsMissingFromPlan,
   AMENDMENT_VACUITY_NOTE,
+  decideSignableSet,
+  signableSetLine,
   decideRecordWrite,
   decideReadBack,
   recordVerdictLine,
@@ -2678,6 +2682,13 @@ async function cmdTeach(options: Map<string, string>, flags: Set<string>, cwd: s
     }
     write(`Imported ${imported} pattern(s) from ${fromJson}`);
     write(`  Skipped ${skipped} (duplicates already in the store, or invalid entries)`);
+    // Carrying a brain to a new machine goes through this path, and the mirror gate is the SAME one
+    // teach uses — so without a config the whole import lands unindexed while `vector status` still
+    // prints `pending: 0`. Say it here, where the user can act on it (FR-6).
+    if (imported > 0 && !flags.has('no-mirror') && !vectorMirrorEnabled(projectRoot)) {
+      write(`  ⚠ the vector mirror writer is OFF — these ${imported} pattern(s) are LEXICAL ONLY`);
+      write(`     enable it in .dz/config.json (memory.backend=agentdb), then run: dz vector reindex`);
+    }
     // Bulk import preserves the DOMAIN of every record, so it can put medical lessons in
     // a shared store as silently as a hand-typed teach — and it returned before the
     // advice single-teach prints. The same advice, at the same point in the flow: after
@@ -3080,6 +3091,45 @@ async function cmdRecallForget(
   return 0;
 }
 
+
+/**
+ * Run `fn` with anything written to STDOUT by code we do not own routed to STDERR instead.
+ *
+ * Used to keep `--json` output parseable: a dependency that greets stdout on first load (currently
+ * transformers.js) would otherwise sit in front of the JSON array. Nothing is swallowed — the text
+ * still reaches the terminal, on the stream diagnostics belong on. Restoration is in `finally`, so a
+ * throwing `fn` cannot leave stdout redirected.
+ */
+export async function withForeignStdoutOnStderr<T>(fn: () => Promise<T>): Promise<T> {
+  // Re-entrant: a nested call must not restore stdout when the INNER scope ends, or the outer scope
+  // silently loses its guard. Depth-counted, and only the outermost exit restores (found by
+  // independent review). Backpressure is not proxied — every writer here emits short diagnostic
+  // lines, and returning stderr's own boolean is closer to the truth than inventing one.
+  // Counted for EVERY caller, nested or concurrent. The first version only incremented when it
+  // installed the patch, so an overlapping call that arrived second was not counted — and when the
+  // FIRST finished it restored stdout while the second was still running, leaking exactly what the
+  // guard exists to catch (found by cross-family review). The original `write` is captured once, by
+  // the caller that installs the patch, and restored by the last one to leave.
+  if (stdoutRedirectDepth === 0) {
+    originalStdoutWrite = process.stdout.write;
+    process.stdout.write = ((chunk: string | Uint8Array, ...rest: unknown[]): boolean =>
+      (process.stderr.write as unknown as (c: string | Uint8Array, ...r: unknown[]) => boolean)(chunk, ...rest)) as typeof process.stdout.write;
+  }
+  stdoutRedirectDepth += 1;
+  try {
+    return await fn();
+  } finally {
+    stdoutRedirectDepth -= 1;
+    // the EXACT original function, not a fresh binding of it
+    if (stdoutRedirectDepth === 0 && originalStdoutWrite !== undefined) {
+      process.stdout.write = originalStdoutWrite;
+      originalStdoutWrite = undefined;
+    }
+  }
+}
+
+let stdoutRedirectDepth = 0;
+let originalStdoutWrite: typeof process.stdout.write | undefined;
 /**
  * `dz recall --promote <dzId>[,<dzId>…] [--apply]` — lift quarantine from NAMED records
  * (lesson-quarantine FR-6b). Dry-run by default, the --forget symmetry. Also clears the
@@ -3226,10 +3276,13 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
   }
 
   if (flags.has('books')) {
-    const { hits, error } = await queryBookKnowledge(projectRoot, query, {
+    // Same guard as the hybrid path: book knowledge is a vector search, so it loads the same
+    // embedder and greeted stdout ahead of the JSON array (found by independent review).
+    const runBooks = (): ReturnType<typeof queryBookKnowledge> => queryBookKnowledge(projectRoot, query, {
       limit,
       ...(bookFilter !== undefined ? { book: bookFilter } : {}),
     });
+    const { hits, error } = asJson ? await withForeignStdoutOnStderr(runBooks) : await runBooks();
     if (asJson) { 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})`);
@@ -3237,6 +3290,34 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
       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}`);
     }
+    // A zero-hit search must say WHERE it looked, and — only then — whether the other shelf has
+    // anything. `--books` reads THIS PROJECT's store; digitised books are promoted to a machine-wide
+    // brain. MEASURED: the same query gives 3 hits in this repository, 0 in any other directory, and
+    // 2 through `dz brain query` from that same other directory — with no sign that the knowledge
+    // was one command away (features/books-names-the-brain).
+    // A FAILED search is not an empty one. With `error` set, `hits` is empty because the store could
+    // not be read — claiming it was searched, and pointing elsewhere, would turn a fault into a
+    // "nothing here" (found by cross-family review; the error itself is already printed above).
+    if (hits.length === 0 && error === undefined) {
+      write(`  searched this project's book store: ${bookKbPath(projectRoot)}`);
+      // Read the brain ONLY here: the happy path must not pay for the empty one. A brain that
+      // cannot be read says NOTHING — an unreadable shelf is not an empty shelf.
+      let sources: { slug: string }[] | undefined;
+      try {
+        sources = listBrain();
+      } catch {
+        sources = undefined;
+      }
+      if (sources !== undefined && sources.length > 0) {
+        // Deliberately NOT asserting that `--book <slug>` exists in the brain — nothing here checked
+        // that, and advising a filter that will also miss is the same defect wearing a hat.
+        // POSIX single-quoting: the query is USER text and lands in a command the reader will paste.
+        // Interpolating it into double quotes breaks on a `"` and invites `$(…)`/backticks to be
+        // read by their shell (found by cross-family review).
+        const quoted = `'${query.replace(/'/g, `'\\''`)}'`;
+        write(`  the machine-wide brain holds ${sources.length} source(s) — search it with: dz brain query ${quoted}`);
+      }
+    }
     return 0;
   }
 
@@ -3264,11 +3345,25 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
   const shownQuery = oneLine(query);
   const shownDomain = wantedDomain === undefined ? undefined : oneLine(wantedDomain);
   const fetchLimit = wantedDomain !== undefined ? Math.min(limit * 3, limit + 20) : limit;
-  const result = await recallHybrid(projectRoot, query, { limit: fetchLimit, mode });
+  // `--json` promises MACHINE-READABLE stdout, and transformers.js writes `Transformers.js loaded:
+  // <model>` straight to stdout when the embedding model loads — so the machine mode was unparseable
+  // in exactly the mode that makes it machine-readable (MEASURED 2026-08-22: it broke this project's
+  // own measurement script and produced a false result). The same noise already forced
+  // `.claude/helpers/agentdb-mcp-shim.mjs` to exist for the MCP stdio channel; this is that class,
+  // second occurrence. Foreign stdout is routed to stderr for the duration of the engine call — our
+  // own output is written after it returns.
+  const result = asJson
+    ? await withForeignStdoutOnStderr(() => recallHybrid(projectRoot, query, { limit: fetchLimit, mode }))
+    : await recallHybrid(projectRoot, query, { limit: fetchLimit, mode });
 
   if (mode === 'semantic' && result.vectorEngine === 'none') {
     // --semantic is an explicit ask — degrading it silently would be dishonest (FR-3).
-    write(`dz recall --semantic: ${result.vectorReason ?? 'no vector engine available — run: dz setup --memory agentdb'}`);
+    const why = result.vectorReason ?? 'no vector engine available — run: dz setup --memory agentdb';
+    // …and under --json the refusal must itself be JSON. This branch wrote PROSE to stdout, so the
+    // one mode that promises machine-readable output broke exactly where the feature is loudest
+    // (found by cross-family review; MEASURED: `--semantic --json` with no engine printed a
+    // sentence). An error the caller cannot parse is not an honest refusal, only a different lie.
+    write(asJson ? JSON.stringify({ error: 'semantic-unavailable', reason: why, hits: [] }) : `dz recall --semantic: ${why}`);
     return 1;
   }
   // Domain-aware re-ranking (health-advisor slice H): `--domain <name>` lifts lessons
@@ -3276,6 +3371,15 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
   // shared store keeps the cross-domain transfers that make it worth more than two stores.
   const boost = wantedDomain !== undefined ? applyDomainBoost(result.hits, wantedDomain) : null;
   const hits = (boost ? boost.hits : result.hits).slice(0, limit);
+  // Computed ONCE, honoured by EVERY return path. It used to live only on the text tail, so the two
+  // paths that return earlier — `--json` and the zero-hits branch — still reported success. That
+  // made the contract change invisible to exactly the caller the ADR justifies it by: a script
+  // (MEASURED: text mode exited 1, `--json` exited 0 on the same query).
+  // `vectorError` is EXCLUDED on purpose: an engine that was asked and failed/timed out is the
+  // documented degraded path (exit 0, 05 §2.3) and stays that way. This code is for a tier that had
+  // nothing to give, not for one that broke — conflating them would make the exit status depend on a
+  // timeout and so vary run to run (found by independent review).
+  const semanticUnserved = mode === 'semantic' && result.vectorError === undefined && result.semanticRanked === 0;
   // The boost never drops a hit, but the CUT still can: promoting a match into the top
   // `limit` pushes the last one out, so a lesson visible WITHOUT --domain can vanish
   // WITH it. Cross-model review called this out as a lie by omission — the note said
@@ -3285,7 +3389,19 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
   if (asJson) {
     // Portable contract UNCHANGED (I-7/AC-6): a plain PatternRecord[] — round-trips through
     // `dz teach --from-json` regardless of which backend ranked each hit.
-    write(JSON.stringify(hits.map((h) => h.pattern)));
+    // The RRF relevance that ranked these very records was computed and then dropped, so no
+    // automated consumer could threshold on it (MEASURED: keys were exactly
+    // pattern,type,reward,domain,ts,source). It rides as a COMPANION key: `dz teach --from-json`
+    // ignores unknown keys, so the round-trip is preserved — PROVEN by running, not assumed.
+    // `relevance` is null under `--domain`: the domain boost REORDERS the list, so the RRF score no
+    // longer explains the order shown, and printing it beside a boosted ranking would be a number
+    // that contradicts its own list. Null means "not applicable here", never "zero relevance".
+    // The condition is the BOOST, not `'score' in h`: boosted hits carry a score too, so the first
+    // version emitted the number while its own comment promised null (found by independent review).
+    write(JSON.stringify(hits.map((h) => ({
+      ...h.pattern,
+      relevance: boost === null && 'score' in h && typeof h.score === 'number' ? h.score : 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
     // that had promoted a match and pushed a visible hit past the --limit cut.
@@ -3294,7 +3410,7 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
       const cutNoteJson = renderDomainCutNote(displaced, limit);
       if (cutNoteJson !== '') process.stderr.write(`${cutNoteJson}\n`);
     }
-    return 0;
+    return semanticUnserved ? 1 : 0;
   }
 
   if (hits.length === 0) {
@@ -3304,11 +3420,29 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
     // silently said nothing about the domain, so the reader could not tell whether the
     // boost had been applied and found nothing, or had not run at all.
     if (boost !== null && shownDomain !== undefined) write(renderDomainBoostNote(boost, shownDomain));
-    return 0;
-  }
-  const vectorOn = result.vectorEngine !== 'none' && result.vectorError === undefined && mode !== 'lexical';
+    return semanticUnserved ? 1 : 0;
+  }
+  // `vectorOn` used to mean "an engine RESOLVED", so the header claimed vector ranking over a store
+  // with zero vectors while each hit's own label honestly read ⟨sqlite⟩ (MEASURED 2026-08-22).
+  // It now means what it says: a vector actually ranked something (ADR-001).
+  const vectorOn = result.semanticRanked > 0 && result.vectorError === undefined && mode !== 'lexical';
+  const engineUp = result.vectorEngine !== 'none' && result.vectorError === undefined;
+  // Whether a tier EXISTS, regardless of whether this query's search succeeded. The advice below
+  // must key on existence: gated on `engineUp`, a timed-out but installed tier was told to install
+  // itself, one line under "vector search degraded" (found by independent review).
+  const engineInstalled = result.vectorEngine !== 'none';
   const lexLabel = result.lexicalBackend === 'sqlite' ? 'SQLite FTS5' : 'keyword (JSON)';
-  const ranking = vectorOn ? `${lexLabel} + vector (${result.vectorEngine}) ranking` : `${lexLabel} ranking (lexical)`;
+  const ranking = vectorOn
+    ? `${lexLabel} + vector (${result.vectorEngine}) ranking`
+    : engineUp && mode !== 'lexical'
+      // the engine is up and returned nothing usable — name the state and the fix, do not claim a
+      // ranking that did not happen and do not advise installing what is already installed
+      // `semanticCandidates` earns its place here: an engine that returned candidates which were ALL
+      // orphans is a different problem from an engine with nothing in it, and the fix differs too.
+      ? result.semanticCandidates > 0
+        ? `${lexLabel} only (the semantic tier returned ${result.semanticCandidates} stale id(s) — run: dz consolidate)`
+        : `${lexLabel} only (semantic tier empty — run: dz vector reindex)`
+      : `${lexLabel} ranking (lexical)`;
   write(`dz recall "${shownQuery}"  —  ${hits.length} hit(s), ${ranking}`);
   let sawQuarantined = false;
   for (const h of hits) {
@@ -3345,10 +3479,20 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
   // FR-8 hint swap: with an engine the old MCP-only hint is gone; without one, the SAME
   // conditional position carries an actionable enablement line instead — the only permitted
   // output change on the degraded path.
-  if (!vectorOn && result.vectorError === undefined && existsSync(join(projectRoot, '.dz', 'agentdb.db'))) {
+  // ... and NOT when the tier is already installed: in the repo (539 vectors, a 2.9 MB agentdb.db)
+  // `--no-semantic` advised installing the tier it was deliberately not using (MEASURED 2026-08-22).
+  // ... and NOT when the user explicitly asked for lexical recall. Under `--no-semantic` the result
+  // reports `vectorEngine: 'none'` BY CONSTRUCTION, so this line fired over a tier that was installed
+  // and full — in this repo, 539 vectors and a 2.9 MB agentdb.db, advising the user to install it
+  // (MEASURED 2026-08-22). Someone who passed --no-semantic has opted out; advice is noise there.
+  if (!vectorOn && !engineInstalled && mode !== 'lexical' && existsSync(join(projectRoot, '.dz', 'agentdb.db'))) {
     write(`  ℹ semantic (vector) recall needs the agentdb vector tier — run: dz setup --memory agentdb`);
   }
-  return 0;
+  // An EXPLICIT --semantic that no vector could serve is not a success. The caller who most needs to
+  // know is the one that cannot read the prose above it (ADR-001; this is a contract change).
+  // Exit 1, the SAME code the documented sibling case uses ("--semantic … exit 1 if no engine"):
+  // an explicit ask that could not be served is one failure class, not two.
+  return semanticUnserved ? 1 : 0;
 }
 
 /* ------------------------------------------------------------------ */
@@ -3433,11 +3577,36 @@ async function cmdVector(options: Map<string, string>, flags: Set<string>, cwd:
     write(`  Mode: ${st.mode} (.dz/config.json → memory.vector.engine)`);
     if (st.embeddingModel !== undefined) write(`  Embedding model: ${st.embeddingModel}`);
     write(`  Lexical patterns: ${st.lexicalMirrorable} mirrorable (${st.lexicalTotal} total)`);
-    write(`  Mirrored vectors: ${st.mirrored !== undefined ? st.mirrored : 'n/a (no engine)'}`);
+    // Each line NAMES its scope. `Mirrored vectors` used to count three task types and sit directly
+    // under a one-task-type lexical count, and a reader took the pair at face value: 547 vs 274 read
+    // as half the index orphaned, and a task was filed to prune it. MEASURED: 273 of those were
+    // `dz-backlog` idea ids and there were ZERO orphans (ADR-001, features/mirror-counts-comparable).
+    write(`  Mirrored vectors (learned patterns): ${st.mirrored !== undefined ? st.mirrored : 'n/a (no engine)'}`);
+    if (st.mirroredOther !== undefined && st.mirroredOther > 0) {
+      write(`  Other dz-owned vectors (backlog ideas): ${st.mirroredOther}  — counted separately, not part of the pair above`);
+    }
+    if (st.orphaned !== undefined && st.orphaned > 0) {
+      write(`  Orphan vectors (no lexical record): ${st.orphaned}  — run: dz vector reindex`);
+    }
     write(`  Pending mirror queue: ${st.pending}`);
-    if (st.available && st.mirrored !== undefined && st.mirrored < st.lexicalMirrorable) {
+    // `pending: 0` used to stand alone, and it reads as "no debt" when it actually means "no queue
+    // was ever opened" — an unconfigured project printed the same line as a fully-mirrored store
+    // (MEASURED: two projects differing by one config file, 0 vs 1 for the same record).
+    write(`  Mirror writer: ${st.mirrorWriterEnabled ? 'ON' : 'OFF (.dz/config.json has no memory.backend=agentdb — teach is NOT queueing)'}`);
+    // "not in the mirror" is ALL the set difference proves — a vector written and later deleted is
+    // indistinguishable from one never offered, so the label must not claim "never queued".
+    // `undefined` has two causes and they are different advice, so they are printed differently.
+    const unknownReason = st.available ? 'unknown (the engine failed to list its ids)' : 'unknown (no engine to ask)';
+    write(`  Not in the mirror: ${st.unmirrored !== undefined ? st.unmirrored : unknownReason}`);
+    // The old advice compared `mirrored < lexicalMirrorable`, two counts of different things — so
+    // backlog ideas inflating `mirrored` could SILENCE it while patterns really were missing.
+    // `unmirrored` is a set difference over ids and answers the same question correctly.
+    if (st.unmirrored !== undefined && st.unmirrored > 0) {
       write(`  ℹ mirror behind the lexical store — run: dz consolidate (backfill)`);
     }
+    if (st.unmirrored !== undefined && st.unmirrored > 0) {
+      write(`  ℹ ${st.unmirrored} mirrorable pattern(s) are not in the vector mirror — run: dz vector reindex`);
+    }
     return 0;
   }
 
@@ -4562,7 +4731,10 @@ function verifyInstalledPacks(cwd: string, explicitPubkey?: string | undefined):
     packaged: packagedTrustRootPath(),
   });
 
-  const packs = discoverSkillPackDirs(cwd);
+  // ADR-001: verification asks "which packs carry a signature?", which is NOT the question
+  // `discoverSkillPackDirs` answers. MEASURED 2026-08-21 — the prefix filter left 26 of 52 signed
+  // packs invisible, `keysarium` drifted unnoticed, and the summary line read as coverage.
+  const packs = discoverVerifiablePackDirs(cwd);
 
   // Cross-model review: `--pubkey <pack>/evil.pub` would let the artifact supply its own verifying key
   // through the caller. The tool must never verify a pack against a key that lives inside it.
@@ -4601,6 +4773,32 @@ function verifyInstalledPacks(cwd: string, explicitPubkey?: string | undefined):
       checks.push({ pack, verdict: 'no-trust-root', failures: [] });
       continue;
     }
+    // A SOURCE tree legitimately holds files the tarball never ships (tests, coverage, CHANGELOG), so
+    // the added-file sweep is meaningless there — scoping it to the manifest's own list disables it.
+    // An INSTALLED pack under node_modules IS the extracted artifact, and there the sweep is the whole
+    // point: it is what catches a file an attacker added. Same function, two honest modes.
+    //
+    // This distinction had to be drawn the moment the SIGNER started covering only the shipped set
+    // (2026-08-21). Leaving it undrawn made every source pack report TAMPERED — the third time in one
+    // day that a scope change on one side was not mirrored on the other.
+    // An ARTIFACT is an extracted tarball, and extracted tarballs live in `node_modules`. Anything
+    // else is a checkout. Deliberately NOT keyed on `cwd`: packs are also discovered from the CLI's
+    // own install location, which is outside the project being checked — keying on cwd made the
+    // repo's own source packs look like artifacts and report TAMPERED from a temp-dir fixture.
+    // Resolve the link FIRST: pnpm links workspace packages into `node_modules`, so a source checkout
+    // is reachable by a path that looks like an artifact. Judging by the given path made the repo's
+    // own packs verify as tarballs and report TAMPERED (measured while wiring this).
+    let realDir = dir;
+    try { realDir = realpathSync(dir); } catch { /* keep the given path */ }
+    const isSourceTree = !realDir.split(sep).includes('node_modules');
+    if (isSourceTree) {
+      // The manifest describes the PUBLISHED TARBALL, and a source checkout is a different object —
+      // `pnpm publish` re-serialises package.json and rewrites `workspace:*`. Hash-verifying a
+      // checkout against it produces a guaranteed false TAMPERED, so this reports a state of its own
+      // instead of an alarm. `dz verify-pack` packs and checks the real artifact.
+      checks.push({ pack, verdict: 'source-tree', failures: [] });
+      continue;
+    }
     const res = verifyManifest(dir, signed as never, keyPem);
     checks.push({
       pack,
@@ -4611,6 +4809,36 @@ function verifyInstalledPacks(cwd: string, explicitPubkey?: string | undefined):
   return { trustRoot, checks };
 }
 
+/**
+ * The signature verdicts as DATA. The text reporter and the `--json` output both render this, so the
+ * two cannot disagree about what was found — the failure this feature removes is exactly a verdict
+ * that exists in one surface and not the other.
+ */
+function collectPackVerification(
+  cwd: string,
+  explicitPubkey: string | undefined,
+): {
+  trustRoot: { source: string; path: string } | null;
+  counts: Record<PackVerdict, number>;
+  packs: { pack: string; verdict: PackVerdict; failures: { path: string; reason: string }[] }[];
+} {
+  let trustRoot: ReturnType<typeof resolveTrustRoot> = null;
+  let checks: PackCheck[] = [];
+  try {
+    ({ trustRoot, checks } = verifyInstalledPacks(cwd, explicitPubkey));
+  } catch {
+    // A refusal is a result: an empty listing with no trust root, not a crash and not a silent pass.
+    return { trustRoot: null, counts: { verified: 0, unsigned: 0, tampered: 0, 'no-trust-root': 0, 'source-tree': 0 }, packs: [] };
+  }
+  const counts: Record<PackVerdict, number> = { verified: 0, unsigned: 0, tampered: 0, 'no-trust-root': 0, 'source-tree': 0 };
+  for (const c of checks) counts[c.verdict]++;
+  return {
+    trustRoot: trustRoot === null ? null : { source: trustRoot.source, path: trustRoot.path },
+    counts,
+    packs: checks.map((c) => ({ pack: c.pack, verdict: c.verdict, failures: [...c.failures] })),
+  };
+}
+
 /** Print the pack verdicts and return 1 iff the policy says any of them is fatal. */
 function reportPackVerification(
   cwd: string,
@@ -4629,7 +4857,7 @@ function reportPackVerification(
   }
   if (checks.length === 0) return 0;
 
-  const counts = { verified: 0, unsigned: 0, tampered: 0, 'no-trust-root': 0 } as Record<PackVerdict, number>;
+  const counts = { verified: 0, unsigned: 0, tampered: 0, 'no-trust-root': 0, 'source-tree': 0 } as Record<PackVerdict, number>;
   let fatal = 0;
   for (const c of checks) {
     counts[c.verdict]++;
@@ -4645,7 +4873,7 @@ function reportPackVerification(
   const root = trustRoot ? `${trustRoot.source} (${trustRoot.path})` : 'none';
   write(
     `  signatures: ${counts.verified} verified, ${counts.unsigned} unsigned, ` +
-      `${counts.tampered} TAMPERED, ${counts['no-trust-root']} unverifiable; trust root: ${root}`,
+      `${counts.tampered} TAMPERED, ${counts['no-trust-root']} unverifiable, ${counts['source-tree']} source-tree (not an artifact); trust root: ${root}`,
   );
   // A signature proves the bytes are unmodified. It never proves the skill is any good.
   return fatal > 0 ? 1 : 0;
@@ -4733,13 +4961,40 @@ function cmdSign(options: Map<string, string>, flags: Set<string>, cwd: string,
   }
   if (!existsSync(resolve(cwd, key))) { write(`dz sign: private key not found: ${resolve(cwd, key)}`); return 1; }
 
-  const files = packFiles(packDir);
-  if (files.length === 0) { write('dz sign: the pack contains no files — refusing to sign nothing'); return 1; }
+  // The manifest covers what the CONSUMER receives. `dz sign` and the publish-time re-sign MUST use
+  // the same rule, or the two produce different manifests for the same pack — a second, divergent
+  // answer beside the real one, which is the class of defect this change removes.
+  // Hash the EXTRACTED TARBALL, not the working tree. `pnpm publish` re-serialises package.json and
+  // rewrites `workspace:*`, so a hash taken from disk is stale before the tarball exists — MEASURED
+  // 2026-08-21: the published `skills-news` package.json is 1050 bytes where the tree's is 1051, and
+  // that single missing newline made six freshly re-signed packs report TAMPERED to every consumer.
+  // `dz sign` and the publish-time re-sign use this same path, or they produce different manifests for
+  // the same pack.
+  let hashRoot = packDir;
+  let cleanupPack: (() => void) | null = null;
+  let files: string[] = packFiles(packDir);
+  try {
+    const extracted = extractPublishTarball(packDir);
+    hashRoot = extracted.dir;
+    cleanupPack = extracted.cleanup;
+    files = packFiles(hashRoot);
+    write(`dz sign: hashing the packed tarball (${files.length} file(s)) — the bytes a recipient receives`);
+  } catch (err) {
+    // Not an npm package, or no pnpm: sign the tree and SAY SO. A silent fallback would restore the
+    // divergence this change closes.
+    write(`dz sign: could not pack this directory (${(err as Error).message.split('\n')[0]}) — signing the working tree instead`);
+  }
+  if (files.length === 0) {
+    cleanupPack?.();
+    write('dz sign: the pack contains no files — refusing to sign nothing');
+    return 1;
+  }
 
-  const manifest = buildManifest(packDir, basename(packDir), files);
+  const manifest = buildManifest(hashRoot, basename(packDir), files);
   const signed = signManifest(manifest, readFileSync(resolve(cwd, key), 'utf8'));
   writeFileSync(join(packDir, MANIFEST_NAME), JSON.stringify(signed, null, 2) + '\n');
   writeFileSync(join(packDir, SBOM_NAME), JSON.stringify(buildSbom(manifest), null, 2) + '\n');
+  cleanupPack?.();
   write(`dz sign: signed ${files.length} file(s) in ${packDir}`);
   write(`  ${MANIFEST_NAME} + ${SBOM_NAME} written. Ed25519 gives tamper-evidence, never truthfulness.`);
   return 0;
@@ -4763,7 +5018,11 @@ function cmdVerifyPack(options: Map<string, string>, flags: Set<string>, cwd: st
   try { signed = JSON.parse(readFileSync(manifestPath, 'utf8')); }
   catch { write(`dz verify-pack: ${MANIFEST_NAME} is not valid JSON`); return 1; }
 
-  const res = verifyManifest(packDir, signed as never, readFileSync(pubPath, 'utf8'));
+  // Same rule as the signer: a working-tree file `files[]` excludes was never "added to the pack".
+  // Unscoped when npm cannot answer — an extracted tarball verifies exactly as before.
+  let shippedForVerify: string[] | undefined;
+  try { shippedForVerify = npmPackedPaths(packDir); } catch { shippedForVerify = undefined; }
+  const res = verifyManifest(packDir, signed as never, readFileSync(pubPath, 'utf8'), shippedForVerify);
   if (res.ok) { write(`dz verify-pack: OK — ${packDir} matches its signed manifest`); return 0; }
   write(`dz verify-pack: FAILED — ${packDir}`);
   for (const f of res.failures) write(`  ${f.path}: ${f.reason}`);
@@ -4936,7 +5195,9 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
       if (trustRootPresent && manifestPresent) {
         try {
           const signed = JSON.parse(readFileSync(manifestPath, 'utf8'));
-          verifyOk = verifyManifest(pk.dir, signed, readFileSync(trustRoot, 'utf8')).ok;
+          let shippedForGate: string[] | undefined;
+          try { shippedForGate = npmPackedPaths(pk.dir); } catch { shippedForGate = undefined; }
+          verifyOk = verifyManifest(pk.dir, signed, readFileSync(trustRoot, 'utf8'), shippedForGate).ok;
         } catch {
           verifyOk = false;
         }
@@ -4967,15 +5228,61 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
     bumpOnly,
     claimGate: claimCheckOpt,
     signKey: signKey === '' ? undefined : resolve(cwd, signKey),
+    verifyAfterSign: (packDir: string): { ok: boolean; trustRootPresent: boolean; pack?: string } => {
+      // Verify the OUTCOME against the trust root a CONSUMER would use — an existing key may be the
+      // WRONG key, and enumerating that state is a losing game (round-1 review). The pack NAME travels
+      // with the verdict so a pass about a different artifact cannot be mistaken for this one.
+      const trustRoot = resolve(cwd, TRUST_ROOT_REL);
+      if (!existsSync(trustRoot)) return { ok: false, trustRootPresent: false, pack: basename(packDir) };
+      try {
+        const signed = JSON.parse(readFileSync(join(packDir, MANIFEST_NAME), 'utf8')) as never;
+        let shipped: string[] | undefined;
+        try { shipped = npmPackedPaths(packDir); } catch { shipped = undefined; }
+        const res = verifyManifest(packDir, signed, readFileSync(trustRoot, 'utf8'), shipped);
+        return { ok: res.ok, trustRootPresent: true, pack: basename(packDir) };
+      } catch {
+        return { ok: false, trustRootPresent: true, pack: basename(packDir) };
+      }
+    },
     reSign: (packDir: string, keyPath: string): void => {
       // The same three steps `dz sign` performs, including the SBOM — a manifest refreshed without
       // its SBOM would leave the two describing different trees.
-      const files = packFiles(packDir);
+      //
+      // Path A: the manifest must cover what the CONSUMER receives, not what the author has on disk.
+      // MEASURED 2026-08-21 by a live install of the published 0.6.1 — with the trust root restored,
+      // six packs reported TAMPERED, and only half of that was the version bump. The rest was
+      // `CHANGELOG.md: listed in the manifest but absent`: signed on disk, excluded by `files[]`,
+      // therefore missing for every recipient forever. So the file list comes from `npm pack`, which
+      // is the authority on what ships — we do not reimplement its globbing.
+      // Hash the EXTRACTED TARBALL, not the working tree. `pnpm publish` re-serialises package.json and
+      // rewrites `workspace:*`, so a hash taken from disk is stale before the tarball exists — MEASURED
+      // 2026-08-21: the published `skills-news` package.json is 1050 bytes where the tree's is 1051,
+      // and that one missing newline is what made six freshly re-signed packs report TAMPERED.
+      const { dir: shippedDir, cleanup } = extractPublishTarball(packDir);
+      try {
+      const onDisk = packFiles(shippedDir);
+      const packed = packFiles(shippedDir);
+      const setDecision = decideSignableSet({ signable: onDisk, packed });
+      write(signableSetLine(basename(packDir), setDecision));
+      if (setDecision.publishedButUnsigned.length > 0) {
+        // A shipped file no signature covers is WORSE than an unsigned pack: the badge says verified
+        // while part of the payload is unchecked. Refuse rather than sign a partial claim.
+        throw new Error(
+          `refusing to sign a pack with ${setDecision.publishedButUnsigned.length} SHIPPED BUT UNSIGNED file(s): ${setDecision.publishedButUnsigned.slice(0, 5).join(', ')}`,
+        );
+      }
+      const files = [...setDecision.sign];
       if (files.length === 0) throw new Error(`refusing to sign an empty pack: ${packDir}`);
-      const manifest = buildManifest(packDir, basename(packDir), files);
+      // Hashes come from the extracted tarball; the manifest is WRITTEN to the source dir so the next
+      // pack carries it. The re-pack normalises package.json identically (deterministic — MEASURED by
+      // packing twice and comparing hashes), so the entries still describe what ships.
+      const manifest = buildManifest(shippedDir, basename(packDir), files);
       const signed = signManifest(manifest, readFileSync(keyPath, 'utf-8'));
       writeFileSync(join(packDir, MANIFEST_NAME), `${JSON.stringify(signed, null, 2)}\n`);
       writeFileSync(join(packDir, SBOM_NAME), `${JSON.stringify(buildSbom(manifest), null, 2)}\n`);
+      } finally {
+        cleanup();
+      }
     },
   });
 
@@ -6428,8 +6735,16 @@ function cmdDriftCheck(options: Map<string, string>, flags: Set<string>, cwd: st
   const r = sweepSkillDrift(root, { scope, allowlist });
 
   if (flags.has('json')) {
-    write(JSON.stringify({ ...r, scope, allowlist }));
-    return r.drifted.length > 0 ? 1 : 0;
+    // The signature verdicts were printed in the TEXT output and absent from the JSON, so a CI job
+    // parsing `--json` saw `drifted: 0` and concluded all was well while packs were TAMPERED. A gate
+    // silent in the form CI reads is not a gate (MEASURED 2026-08-21: keys were duplicated, drifted,
+    // allowlisted, scope, allowlist — and nothing else).
+    const sig = collectPackVerification(root, options.get('pubkey'));
+    const sigBlocking = sig.packs.filter(
+      (c) => decideVerifyPolicy(c.verdict, flags.has('require-signing')).action === 'fail',
+    ).length;
+    write(JSON.stringify({ ...r, scope, allowlist, signatures: sig }));
+    return r.drifted.length > 0 || sigBlocking > 0 ? 1 : 0;
   }
 
   write(`Skills duplicated across ≥2 ${scope === 'packages' ? 'package' : ''} locations: ${r.duplicated}`);
@@ -6483,7 +6798,7 @@ const DEFAULT_STORE_CAP = 5000;
 const MAX_STUB_SCAN_FILES = 400;
 
 /** Read the optional `.dz/guard.json` — `{ rules?: [...], storeCap?: number, stubWaivers?: [...] }`. Missing/broken ⇒ defaults. */
-function loadGuardConfig(root: string): { rules?: unknown[]; storeCap?: number; stubWaivers?: unknown[] } {
+function loadGuardConfig(root: string): { rules?: unknown[]; storeCap?: number; stubWaivers?: unknown[]; reviewRound?: { minGrade?: unknown } } {
   const p = join(root, '.dz', 'guard.json');
   if (!existsSync(p)) return {};
   try {
@@ -6630,6 +6945,51 @@ function gatherGuardFacts(op: string, root: string, text: string | undefined, st
       facts['readmeFirst'] = [...perPack.entries()].map(([name, e]) => ({ name: '@dzhechkov/' + name, versionBumped: e.pkgJson, readmeChanged: e.readme }));
     } catch { /* not a git repo — rule skips */ }
 
+    // review-round: the same WORKING-TREE diff, asked a different question — does a package that
+    // bumps its version and changes SOURCE bring a GRADED QE report with it? Scoped to source so a
+    // docs-only republish is never blocked (ADR-001, features/publish-needs-a-review). A throw here
+    // leaves the whole fact undefined, and the rule then reports NOTHING: absence of a report is an
+    // accusation, absence of facts is ignorance, and they must not render the same.
+    try {
+      const status = execSync('git status --porcelain -uall', { cwd: root, encoding: 'utf-8' });
+      const changed = status.split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
+      const perPack = new Map<string, { versionBumped: boolean; sourceChanged: boolean }>();
+      for (const rel of changed) {
+        const m = rel.match(/^packages\/@dzhechkov\/([^/]+)\/(.+)$/);
+        if (!m || !m[1] || !m[2]) continue;
+        const e = perPack.get(m[1]) ?? { versionBumped: false, sourceChanged: false };
+        if (m[2] === 'package.json') e.versionBumped = true;
+        // SOURCE = what ships and can be wrong at runtime. Tests, docs and fixtures are excluded:
+        // a test-only change still ships, but it is not the class the review gate is about, and
+        // widening the scope is what makes a HARD gate get switched off.
+        if (/^(src|lib|bin|skills)\//.test(m[2]) && !/\.(md|json|txt)$/.test(m[2])) e.sourceChanged = true;
+        perPack.set(m[1], e);
+      }
+      const grades: { report: string; grade: string }[] = [];
+      for (const rel of changed) {
+        if (!/^features\/[^/]+\/08_qe_report\.md$/.test(rel)) continue;
+        let text: string;
+        try { text = readFileSync(join(root, rel), 'utf-8'); } catch { continue; }
+        // The grade the report itself STATES — `grade C`, `GRADE: B`, `**grade: A**`. A report that
+        // never states one is not evidence (AM-2), so nothing is pushed for it.
+        const m = text.match(/\bgrade\s*:?\s*\**\s*([ABCDF])\b/i);
+        if (m && m[1]) grades.push({ report: rel, grade: m[1] });
+      }
+      const cfgMin = loadGuardConfig(root).reviewRound?.minGrade;
+      const minGrade = typeof cfgMin === 'string' ? cfgMin : undefined;
+      facts['reviewRound'] = {
+        packages: [...perPack.entries()].map(([name, e]) => ({ name: '@dzhechkov/' + name, ...e })),
+        grades,
+        gathered: true,
+        ...(minGrade !== undefined ? { minGrade } : {}),
+      };
+    } catch {
+      // TRIED and could not read the tree. Say so on the record rather than passing silently: a HARD
+      // gate that is quiet about ungathered evidence cannot be told from one that checked (raised by
+      // cross-family review). It still does not BLOCK — ignorance is not an accusation.
+      facts['reviewRound'] = { packages: [], grades: [], gathered: false };
+    }
+
     // skills-registrable: every skill dir in a skill pack must carry a depth-1 SKILL.md, or it ships
     // registering nowhere (the health-advisor 1.2.0 class). Pure-toolkit packages yield nothing.
     try {
@@ -9009,6 +9369,52 @@ function scanOneReqeRoot(
  * the exit code. A courier can neither refuse nor verify, which is how four workflow runs finished
  * with no cost row at all.
  */
+/**
+ * The file list of the tarball `npm pack` would produce, `package/` prefix stripped. npm is the
+ * authority on what `files[]` ships; reimplementing its globbing would put a second, divergent answer
+ * next to the real one — which is the class of defect this whole change exists to remove.
+ */
+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
+  // to the working tree, `pnpm pack` emits 1050 — pnpm re-serialises it (dropping the trailing
+  // newline, and expanding `workspace:*`). Asking one tool what ships while a different tool ships it
+  // is how a signature ends up describing a file nobody receives.
+  const out = execFileSync('pnpm', ['pack', '--pack-destination', mkdtempSync(join(tmpdir(), 'dz-pack-probe-')), '--json'], {
+    cwd: packDir,
+    encoding: 'utf-8',
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  const parsed = JSON.parse(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();
+}
+
+/**
+ * Pack the package with the SAME tool that publishes it, extract the tarball, and return the directory
+ * holding its contents. Hashing THAT is the only way a manifest can describe what a recipient gets:
+ * `pnpm publish` re-serialises package.json and rewrites `workspace:*`, so any hash taken from the
+ * working tree is stale before the tarball exists.
+ */
+function extractPublishTarball(packDir: string): { dir: string; cleanup: () => void } {
+  const tmp = mkdtempSync(join(tmpdir(), 'dz-sign-pack-'));
+  const out = execFileSync('pnpm', ['pack', '--pack-destination', tmp, '--json'], {
+    cwd: packDir,
+    encoding: 'utf-8',
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  const parsed = JSON.parse(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}`);
+  // pnpm reports an ABSOLUTE filename (it already contains --pack-destination); joining again would
+  // double the directory. npm reports a bare name. Accept both rather than assuming either.
+  const tgzPath = isAbsolute(tgz) ? tgz : join(tmp, tgz);
+  execFileSync('tar', ['-xzf', tgzPath, '-C', tmp]);
+  return { dir: join(tmp, 'package'), cleanup: (): void => { try { rmSync(tmp, { recursive: true, force: true }); } catch { /* best-effort */ } } };
+}
+
 function cmdFeatureAdrRecord(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
   const json = flags.has('json');
   const kind = (options.get('kind') ?? '').trim() as RecordKind;