@dzhechkov/harness-cli 0.6.0 → 0.7.0

package/dist/cli.js

@@ -10,9 +10,9 @@ import { execFileSync, execSync, spawn } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import { homedir, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
-import { createSkill, getSkillInfo, listSkillsDetailed, formatSkillLoadFailures, formatSkillApplyFailures, resolveTargetName, formatTargetProblem, formatTargetAliasNote, TARGET_NAMES_SORTED, runDoctor, runInit, resolvePackageSkillRoots, PACKAGE_SKILL_LAYOUTS, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, runSyncAgentsPolicy, runSyncCodexHooks, resolveCodexHome, withNamedLockSync, 
+import { createSkill, getSkillInfo, listSkillsDetailed, formatSkillLoadFailures, formatSkillApplyFailures, resolveTargetName, formatTargetProblem, formatTargetAliasNote, TARGET_NAMES_SORTED, runDoctor, runInit, resolvePackageSkillRoots, PACKAGE_SKILL_LAYOUTS, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, discoverVerifiablePackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, runSyncAgentsPolicy, runSyncCodexHooks, resolveCodexHome, withNamedLockSync, 
 // dz workflow run (feature dz-workflow-run): the pure scheduler + the dispatch adapters.
-TRACE_RUNID_RE, WF_RUN_OWNER_HOST, preflight, runWorkflow, makeClaudePDispatcher, makeCodexExecDispatcher, NamedLockTimeoutError, NamedLockCompromisedError, POLICY_SOURCES, detectPolicyDrift, hasPolicyFence, TARGET_NAMES, buildParityMatrix, downgradeForStaleEvidence, findStaleTranscriptEvidence, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_TEMPLATES_RETIRED_MESSAGE, parsePlan, isParseErrors, validatePlan, normalizePlan, planDigest, toTraceProjection, renderPlan, mergeRender, lint, lintExitCode, LOOP_BLOBS, parseTrace, assembleTimeline, runInvariants, deriveAttestation, stampAttestation, corroborate, NOT_WITNESSED, renderTimelineHtml, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveCostLedger, renderCostLedger, verifyCostLedgerReport, writeCostLedgerJsonl, COST_LEDGER_SCOPE, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, parseWeeklyResetAnchor, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, EVENT_CHAIN_TAIL_BYTES, EMPTY_LOG_TAIL, readTailInfo, appendChainedLines, verifyEventChainText, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, scannableStubPath, 
+TRACE_RUNID_RE, WF_RUN_OWNER_HOST, preflight, runWorkflow, makeClaudePDispatcher, makeCodexExecDispatcher, NamedLockTimeoutError, NamedLockCompromisedError, POLICY_SOURCES, detectPolicyDrift, hasPolicyFence, TARGET_NAMES, buildParityMatrix, downgradeForStaleEvidence, findStaleTranscriptEvidence, TARGET_CAPABILITIES, TARGET_SHORT_LABELS, WORKFLOW_TEMPLATES_RETIRED_MESSAGE, parsePlan, isParseErrors, validatePlan, normalizePlan, planDigest, toTraceProjection, renderPlan, mergeRender, lint, lintExitCode, LOOP_BLOBS, parseTrace, assembleTimeline, runInvariants, deriveAttestation, stampAttestation, corroborate, NOT_WITNESSED, renderTimelineHtml, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, lessonDeltaReport, removePatternsByIds, snapshotStore, recallHybrid, teachGuard, mirrorPatternsToVector, mirrorEntriesToVector, patternVectorEntry, readMemoryLearningConfig, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns, clearAgentdbQuarantine, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, deriveCostLedger, renderCostLedger, verifyCostLedgerReport, writeCostLedgerJsonl, COST_LEDGER_SCOPE, deriveUsageCalibration, normalizeClaudeUsageModelKey, readUsageLimits, parseWeeklyResetAnchor, claimCheck, summarize, queryBookKnowledge, loadStorePatternsSync, patternRecordId, loadStoreRecords, recordToPattern, bundleSkills, brainHome, listBrain, bookKbPath, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, RECALL_USAGE_LOG_RELATIVE, RECALL_USAGE_LOG_MAX_BYTES, parseRecallUsageLog, buildRecallUsageReport, EVENT_CHAIN_TAIL_BYTES, EMPTY_LOG_TAIL, readTailInfo, appendChainedLines, verifyEventChainText, buildManifest, buildSbom, resolveTrustRoot, decideVerifyPolicy, generateSigningKeypair, evaluateGuard, resolveRules, auditRecord, guardExitCode, DEFAULT_RULES, parsePnpmLockImporters, scannableStubPath, 
 // guard-promotion (feature guard-promotion, scout idea #1)
 assembleCandidates, renderPromotionReport, renderPromotionAdr, normalizePromotionState, nextPromotionState, globMatch, promotionAdrRelPath, DEFAULT_WINDOW_DAYS, DEFAULT_PERIODS, MAX_CONTENT_FETCHES, BUILTIN_COVERAGE, decideProvenance, isInsideTree, signManifest, verifyManifest, listSignablePackFiles, assertKeyOutsideTree, decidePublishGate, collectPackageFacts, planReleaseGates, selectAffectedPackages, classifyGateExecutions, buildFailureIssue, buildReleaseNotes, releaseTagName, firstOutputLine, formatPublishError, MANIFEST_NAME, SBOM_NAME, buildArchitectureMap, renderMapHuman, findArchitectureDrift, renderDriftReport, scanWorkspacePackages, loadSubsystemManifest, loadProductVision, checkFeatureAgainstArchitecture, renderArchCheck, planProjectSkills, guidanceForStage, renderInjectionReport, analyzeCorpus, renderRakeReport, renderCriticSection, rakeAsLesson, rakeReward, DEFAULT_RAKE_THRESHOLDS, streamSessionEvents, findLatestTranscript, detectProcessRakes, buildRetro, renderRetro, retroLessonText, PROCESS_SIGNATURES, RETRO_DOMAIN, scanForSetup, buildSetupPlan, scaffoldFromSpec, renderScaffoldPreview, readExistingForScaffold, assembleChallengeContext, buildChallengeBrief, planDiscriminationCheck, classifyDiscrimination, classifyExecutionEvidence, pickAdversaryModel, CHALLENGE_QUESTIONS, loadOutcomes, renderOutcomes, statsForKey, selectAutoCost, recordProvisional, finalizeOutcome, harvestStageOutcomes, recommendModels, planFeed, GRADE_SUCCESS_FLOOR, COST_LADDER, splitScenarios, budgetPlan, selectWinner, proseScopeOk, renderProseDiff, readScenarioIds, DEFAULT_MAX_JUDGE_RUNS, collectDeliveryFacts, planDeliveryCheck, renderDeliveryBrief, classifyDelivery, isUsablePlaneResult, renderDeliveryReview, scanSkillsLayout, declaredPluginSurface, parseInitFacts, verifyRegistration, buildContentProbePrompt, classifyContentProbe, renderContentProbe, findNonRegistrableSkillDirs, assembleCompoundingReport, 
 // Cold-vs-warm EPOCH RUNNER (feature epoch-replay) — orchestrates + scores, never calls a model.
@@ -22,7 +22,7 @@ readBacklogConfig, readIdeas, writeIdeas, ideaId, dedupIdea, readGoalMap, readGo
 // qe-bridge (feature qe-bridge-claude, ADR-001): the pure half of the reverse QE bridge.
 KNOWN_CLAUDE, isSafeClaudeId, claudeProbeArgs, claudeReviewArgs, interpretClaudeProbe, modelFamily, buildBridgePrompt, parseBridgeOutput, buildBridgeFailureRecord, buildBridgeSignoffRecord, renderBridgeReport, isSafeSlug, hasUnsafePathChars, hasDotDotSegment, buildReqeBrief, settleReqeDebt, renderReqeList, REQE_SCOPE, 
 // Mutation gate (feature ha-mutation-gate) — break each named protection, run the suite, require red.
-parseMutationRegistry, applyMutationToText, countFailingTests, classifyBaseline, classifyRunFailure, classifyMutationOutcome, mutationGateExitCode, summarizeMutationResults, renderMutationReport, TRACE_BUNDLE_LEDGER_PATH, TRACE_BUNDLE_SCHEMA, TRACE_BUNDLE_RUN_META_FILE, buildBundle, serializeBundle, parseBundle, planImport, decideCheckpointWrite, } from '@dzhechkov/harness-core';
+parseMutationRegistry, applyMutationToText, countFailingTests, classifyBaseline, classifyRunFailure, classifyMutationOutcome, mutationGateExitCode, summarizeMutationResults, renderMutationReport, TRACE_BUNDLE_LEDGER_PATH, TRACE_BUNDLE_SCHEMA, TRACE_BUNDLE_RUN_META_FILE, buildBundle, serializeBundle, parseBundle, planImport, decideCheckpointWrite, amendmentSection, planSaysNoAmendments, parseAmendments, resolveAmendments, decideAmendmentOutcome, amendmentVerdictLine, amendmentsMissingFromPlan, AMENDMENT_VACUITY_NOTE, decideSignableSet, signableSetLine, decideRecordWrite, decideReadBack, recordVerdictLine, } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 const USAGE = `dz - DZ cross-platform harness CLI
@@ -62,6 +62,8 @@ Usage:
   dz epoch-replay --judge <filled-work-order.json> [--out <file>]   (blind judge prompts from the filled plans)
   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 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)
+  dz feature-adr-record --kind ledger|training-pair --stage <s> [--slug <s>] [--row|--pair <json>] [--mark <n>] [--once] [--json]   (the witnessed writer for the run-cost ledger and training pairs: the payload arrives as an ARGUMENT, never as shell; a malformed or wrong-kind payload is REFUSED before any write; the timestamp is stamped before serialising; the append is verified by re-reading the tail. exit 0 written|duplicate|skipped, 2 refused, 3 not-verified — a record failure is never blocking)
   dz feature-adr-checkpoint (--slug <feature> | --feature-dir <abs>) --stage <s> --input-hash <h> --result <json> [--artifact a,b] [--json]   (record a pipeline stage ONLY after measuring its artifacts on disk; refuses a null result, an absent artifact, or a stage that declares none — the subagent runs a COMMAND instead of hand-writing durable state)
   dz reqe [--slug <feature> [--done --report <f>]] [--json]   (the re-QE debt ledger: a usage-switched run whose Step-8 QE ran on the coder's OWN family records a debt; list debts, print the cross-family review brief, settle FAIL-CLOSED against a graded report — the settlement lands in 08_qe_report.md)
   dz qe-bridge --family claude --slug <feature> [--coder-family codex|claude] [--model <id>] [--files a,b] [--out <f>] [--timeout <s>] [--allow-same-family] [--json]   (the REVERSE QE bridge: run an INDEPENDENT Claude reviewer over a feature's Step-8 artifacts from ANY host — a Codex session included, plain shell, no Claude agent plane needed — and land a PARSED signoff. The reviewer runs ISOLATED: an EMPTY temp cwd plus --safe-mode --strict-mcp-config --tools '' --no-session-persistence, so no CLAUDE.md/skills/plugins/hooks/MCP load, and the verdict is read from the --output-format json RESULT ENVELOPE — text a session customization printed onto the same stdout can never become a signoff. Probes the model before trusting it; sends SCOPED extracts with a loud 200k-char ceiling (never silent truncation); the grade must AGREE across three LAST-anchored channels (terminal marker line, fenced qe-bridge-signoff JSON, the report's own GRADE line) AND the marker must be the FINAL content — empty, gradeless, self-contradicting or miscounted output is one of 18 NAMED failures with an audit record under features/<slug>/.fa-state/qe-bridge/ (runId, resolved executable + binOverride, prompt sha256, channel offsets, requestedOut, reportWritten, retained raw stdout; 0600 files in a 0700 dir), never a clean review. A --coder-family that contradicts the recorded reqe debt is refused. Writes features/<slug>/08b_reqe_report.md, which dz reqe --done settles unchanged. DISCLOSURE: the extracts you scope are sent to the Claude runtime; the bridge cannot classify secrets. DZ_QE_BRIDGE_CLAUDE_BIN is a TEST SEAM, not a flag. exit 0 signoff parsed (ANY grade — it reports, it does not gate) / 1 named failure / 2 usage)
@@ -2166,6 +2168,13 @@ async function cmdTeach(options, flags, cwd, write) {
         }
         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
@@ -2579,6 +2588,43 @@ async function cmdRecallForget(options, flags, projectRoot, write) {
     write('  the vector mirror still holds them — run `dz vector reindex` to resync');
     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(fn) {
+    // 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, ...rest) => process.stderr.write(chunk, ...rest));
+    }
+    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;
 /**
  * `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
@@ -2725,10 +2771,13 @@ async function cmdRecall(options, flags, cwd, write) {
         return 1;
     }
     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 = () => 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;
@@ -2740,6 +2789,35 @@ async function cmdRecall(options, flags, cwd, write) {
             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;
+            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;
     }
     // Hybrid recall (dz-rvf-vector-bridge FR-3): lexical FIRST (unchanged baseline), then a
@@ -2766,10 +2844,24 @@ async function cmdRecall(options, flags, cwd, write) {
     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
@@ -2777,6 +2869,15 @@ async function cmdRecall(options, flags, cwd, write) {
     // 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
@@ -2786,7 +2887,19 @@ async function cmdRecall(options, flags, cwd, write) {
     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.
@@ -2796,7 +2909,7 @@ async function cmdRecall(options, flags, cwd, write) {
             if (cutNoteJson !== '')
                 process.stderr.write(`${cutNoteJson}\n`);
         }
-        return 0;
+        return semanticUnserved ? 1 : 0;
     }
     if (hits.length === 0) {
         write(`dz recall "${shownQuery}"`);
@@ -2806,11 +2919,29 @@ async function cmdRecall(options, flags, cwd, write) {
         // 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) {
@@ -2849,10 +2980,20 @@ async function cmdRecall(options, flags, cwd, write) {
     // 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;
 }
 /* ------------------------------------------------------------------ */
 /*  vector — the semantic-tier observability + export surface (FR-10)  */
@@ -2933,11 +3074,36 @@ async function cmdVector(options, flags, cwd, write) {
         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;
     }
     if (sub === 'reindex') {
@@ -4030,7 +4196,10 @@ function verifyInstalledPacks(cwd, explicitPubkey) {
         repo: existsSync(repoKey) ? repoKey : 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.
     if (trustRoot?.source === 'explicit') {
@@ -4069,6 +4238,35 @@ function verifyInstalledPacks(cwd, explicitPubkey) {
             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, keyPem);
         checks.push({
             pack,
@@ -4078,6 +4276,30 @@ function verifyInstalledPacks(cwd, explicitPubkey) {
     }
     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, explicitPubkey) {
+    let trustRoot = null;
+    let checks = [];
+    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 = { 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, explicitPubkey, requireSigning, write) {
     let trustRoot;
@@ -4092,7 +4314,7 @@ function reportPackVerification(cwd, explicitPubkey, requireSigning, write) {
     }
     if (checks.length === 0)
         return 0;
-    const counts = { verified: 0, unsigned: 0, tampered: 0, 'no-trust-root': 0 };
+    const counts = { verified: 0, unsigned: 0, tampered: 0, 'no-trust-root': 0, 'source-tree': 0 };
     let fatal = 0;
     for (const c of checks) {
         counts[c.verdict]++;
@@ -4108,7 +4330,7 @@ function reportPackVerification(cwd, explicitPubkey, requireSigning, write) {
     }
     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;
 }
@@ -4212,15 +4434,40 @@ function cmdSign(options, flags, cwd, write) {
         write(`dz sign: private key not found: ${resolve(cwd, key)}`);
         return 1;
     }
-    const files = packFiles(packDir);
+    // 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 = null;
+    let files = 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.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;
@@ -4251,7 +4498,16 @@ function cmdVerifyPack(options, flags, cwd, write) {
         write(`dz verify-pack: ${MANIFEST_NAME} is not valid JSON`);
         return 1;
     }
-    const res = verifyManifest(packDir, signed, 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;
+    try {
+        shippedForVerify = npmPackedPaths(packDir);
+    }
+    catch {
+        shippedForVerify = undefined;
+    }
+    const res = verifyManifest(packDir, signed, readFileSync(pubPath, 'utf8'), shippedForVerify);
     if (res.ok) {
         write(`dz verify-pack: OK — ${packDir} matches its signed manifest`);
         return 0;
@@ -4308,7 +4564,7 @@ function cmdPublish(options, flags, cwd, write) {
     // Reject unknown flags/options so a typo (e.g. `--dry-rum`) can NEVER be
     // silently swallowed and flip the command into live-publish mode.
     const allowedFlags = new Set(['dry-run', 'no-dry-run', 'yes', 'confirm', 'bump-only', 'help', 'require-signing', 'provenance', 'no-provenance']);
-    const allowedOptions = new Set(['filter', 'claim-check', 'no-guard']);
+    const allowedOptions = new Set(['filter', 'claim-check', 'no-guard', 'sign-key']);
     const allowedHelp = '  allowed: --dry-run (default), --yes/--confirm/--no-dry-run (go live), --bump-only, --filter <substr>, --claim-check <off|warn|error>, --no-guard "<reason>" (skip the guard pre-flight; logged)';
     for (const flag of flags) {
         if (!allowedFlags.has(flag)) {
@@ -4439,7 +4695,14 @@ function cmdPublish(options, flags, cwd, write) {
             if (trustRootPresent && manifestPresent) {
                 try {
                     const signed = JSON.parse(readFileSync(manifestPath, 'utf8'));
-                    verifyOk = verifyManifest(pk.dir, signed, readFileSync(trustRoot, 'utf8')).ok;
+                    let shippedForGate;
+                    try {
+                        shippedForGate = npmPackedPaths(pk.dir);
+                    }
+                    catch {
+                        shippedForGate = undefined;
+                    }
+                    verifyOk = verifyManifest(pk.dir, signed, readFileSync(trustRoot, 'utf8'), shippedForGate).ok;
                 }
                 catch {
                     verifyOk = false;
@@ -4459,7 +4722,82 @@ function cmdPublish(options, flags, cwd, write) {
             return 1;
         }
     }
-    const report = publishPackages(cwd, { provenance, dryRun, filter, bumpOnly, claimGate: claimCheckOpt });
+    // A signed pack must be RE-SIGNED after publish's own bump and README sync (feature
+    // `sign-after-bump`): publish mutates the pack, so any earlier signature describes files that no
+    // longer exist. Default to the same path `dz sign --init` writes, so the ordinary operator needs no
+    // new flag; `--sign-key` overrides it.
+    const signKey = (options.get('sign-key') ?? join(homedir(), '.dz', 'keys', 'dz.key')).trim();
+    const report = publishPackages(cwd, {
+        provenance,
+        dryRun,
+        filter,
+        bumpOnly,
+        claimGate: claimCheckOpt,
+        signKey: signKey === '' ? undefined : resolve(cwd, signKey),
+        verifyAfterSign: (packDir) => {
+            // 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'));
+                let shipped;
+                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, keyPath) => {
+            // The same three steps `dz sign` performs, including the SBOM — a manifest refreshed without
+            // its SBOM would leave the two describing different trees.
+            //
+            // 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}`);
+                // 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();
+            }
+        },
+    });
     write(`\ndz publish${dryRun ? ' --dry-run' : ''}${bumpOnly ? ' --bump-only' : ''}${claimCheckOpt !== 'warn' ? ` --claim-check ${claimCheckOpt}` : ''}`);
     write(`  Published: ${report.published}  Skipped: ${report.skipped}  Errors: ${report.errors}\n`);
     for (const pkg of report.packages) {
@@ -5888,8 +6226,14 @@ function cmdDriftCheck(options, flags, cwd, write) {
     const allowlist = readDriftAllowlist(root);
     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}`);
     if (r.allowlisted.length > 0) {
@@ -6102,6 +6446,61 @@ function gatherGuardFacts(op, root, text, storeCap) {
             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();
+            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 = [];
+            for (const rel of changed) {
+                if (!/^features\/[^/]+\/08_qe_report\.md$/.test(rel))
+                    continue;
+                let text;
+                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 {
@@ -8634,6 +9033,265 @@ function scanOneReqeRoot(featuresDir, keyMatchesDir, out, addMalformed) {
  * It measures `--artifact` paths on disk itself. A caller cannot assert presence; it can only name
  * what must be there.
  */
+/**
+ * `dz amendment-check` — the deterministic half of the Step-8 amendment gate (ADR-001).
+ *
+ * The gate used to be prompt text asking the QE agent to confirm every `AM-N` row names a real test.
+ * That is layer 4 on the cost-of-detection ladder, and `features/qe-scoped-review` shipped with five
+ * dangling ids and a plan recording `## Amendments: None`. This command owns I/O and the exit code;
+ * `harness-core/src/amendment-trace.ts` owns the grammar and the rules.
+ */
+/**
+ * `dz feature-adr-record` — the witnessed writer for the run-cost ledger and training pairs
+ * (ADR-001 … ADR-003). The subagent stops being a COURIER handed a shell pipeline and becomes a
+ * CALLER handed arguments: this command owns the paths, the refusal, the append, the READ-BACK and
+ * 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) {
+    // `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);
+    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) {
+    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);
+    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: () => { try {
+            rmSync(tmp, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ } } };
+}
+function cmdFeatureAdrRecord(options, flags, cwd, write) {
+    const json = flags.has('json');
+    const kind = (options.get('kind') ?? '').trim();
+    const stage = (options.get('stage') ?? '').trim();
+    const slug = (options.get('slug') ?? '').trim();
+    const payloadRaw = options.get('row') ?? options.get('pair') ?? '';
+    const emit = (d, extra = {}) => {
+        if (json) {
+            write(JSON.stringify({ ok: d.exit === 0, kind, stage, verdict: d.verdict, exit: d.exit, reason: d.reason, blocking: d.blocking, ...extra }));
+        }
+        else {
+            write(recordVerdictLine(kind === 'ledger' || kind === 'training-pair' ? kind : 'ledger', stage, d));
+        }
+        return d.exit;
+    };
+    if (kind !== 'ledger' && kind !== 'training-pair') {
+        write('dz feature-adr-record: --kind must be ledger or training-pair');
+        return 2;
+    }
+    if (payloadRaw === '') {
+        write('dz feature-adr-record: --row (ledger) or --pair (training-pair) is required');
+        return 2;
+    }
+    const repo = (options.get('project') ?? cwd).trim() || cwd;
+    const target = kind === 'ledger'
+        ? join(repo, '.dz', 'feature-adr', 'run-cost-ledger.jsonl')
+        : join(repo, '.dz', 'fa-training', slug === '' ? 'unknown' : slug, `${stage.replace(/[^\w.-]/g, '_')}.jsonl`);
+    const markDir = join(repo, '.dz', 'fa-training', '.backfill-marks');
+    const markName = (options.get('mark') ?? '').trim();
+    const markPath = markName === '' ? null : join(markDir, markName.replace(/[^\w.-]/g, '_'));
+    const decision = decideRecordWrite({
+        kind,
+        payloadRaw,
+        stage,
+        stageProducedResult: flags.has('no-result') ? false : true,
+        markExists: markPath !== null && existsSync(markPath),
+        targetExists: existsSync(target),
+        targetHasPair: flags.has('once') && existsSync(target),
+        timestamp: new Date().toISOString(),
+    });
+    if (decision.line === null)
+        return emit(decision);
+    // MEASURE, never assume: an unwritable target is a LOUD refusal, because a swallowed mkdir failure
+    // is exactly how a write becomes a silent no-op (acid case A4).
+    try {
+        mkdirSync(dirname(target), { recursive: true });
+        if (markPath !== null) {
+            mkdirSync(markDir, { recursive: true });
+            mkdirSync(markPath);
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (markPath !== null && code === 'EEXIST') {
+            // A stale mark (target absent) was already decided as writable above; re-taking it is a no-op,
+            // not a duplicate. Only a mark WITH its target means another run got here first.
+            if (decision.staleMark !== true) {
+                return emit({ verdict: 'duplicate', exit: 0, reason: 'a mark for this record already exists — another run captured it first', blocking: false, line: null });
+            }
+        }
+        return emit({ verdict: 'refused', exit: 2, reason: `the target could not be prepared: ${err.message}`, blocking: false, line: null });
+    }
+    try {
+        appendFileSync(target, `${decision.line}\n`, 'utf-8');
+    }
+    catch (err) {
+        return emit({ verdict: 'refused', exit: 2, reason: `the append failed: ${err.message}`, blocking: false, line: null });
+    }
+    // ADR-002: the write is verified against the disk, never inferred from the absence of an error.
+    let lastLine = null;
+    try {
+        const body = readFileSync(target, 'utf-8');
+        const lines = body.split('\n').filter((l) => l !== '');
+        lastLine = lines.length > 0 ? lines[lines.length - 1] : null;
+    }
+    catch {
+        lastLine = null;
+    }
+    return emit(decideReadBack(decision.line, lastLine), { target });
+}
+function cmdAmendmentCheck(options, flags, cwd, write) {
+    const json = flags.has('json');
+    const readOr = (abs) => {
+        try {
+            return readFileSync(abs, 'utf-8');
+        }
+        catch {
+            return null;
+        }
+    };
+    const checkOne = (featureDir) => {
+        const slug = basename(featureDir);
+        const ideation = readOr(join(featureDir, '03.5_ideation_report.md'));
+        const plan = readOr(join(featureDir, '06_implementation_plan.md'));
+        if (ideation === null) {
+            return {
+                slug,
+                resolutions: [],
+                decision: decideAmendmentOutcome({ sectionPresent: false, rows: [], resolutions: [], planSaysNone: false }),
+            };
+        }
+        const sectionPresent = amendmentSection(ideation) !== null;
+        const ideationRows = parseAmendments(ideation);
+        const planRows = plan === null ? [] : parseAmendments(plan);
+        // The PLAN is authoritative when it carries rows: Step 6 owes "carry AM-N into the plan
+        // verbatim", and the ideation report is the historical record — rewriting its rows to match
+        // tests named later would close the trail by falsifying it. Coverage keeps that honest below.
+        const rows = planRows.length > 0 ? planRows : ideationRows;
+        const missingFromPlan = planRows.length > 0 ? amendmentsMissingFromPlan(ideationRows, planRows) : [];
+        // Paths in an amendment row are repo-relative, so they resolve against the repo root — not
+        // against the feature directory, and not against wherever the caller happened to stand.
+        const resolutions = resolveAmendments(rows, { readFile: (rel) => readOr(resolve(cwd, rel)) });
+        const decision = decideAmendmentOutcome({
+            sectionPresent,
+            rows,
+            resolutions,
+            planSaysNone: plan !== null && planSaysNoAmendments(plan),
+            missingFromPlan,
+        });
+        return { slug, decision, resolutions };
+    };
+    // --all is a CENSUS, not a gate (ADR-003): a gate that is red on arrival over 21 historical
+    // features gets disabled, and then the mechanism is gone along with the debt it was to surface.
+    if (flags.has('all')) {
+        const featuresDir = join(cwd, 'features');
+        let slugs = [];
+        try {
+            slugs = readdirSync(featuresDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+        }
+        catch {
+            if (json)
+                write(JSON.stringify({ ok: true, mode: 'all', features: [], note: 'no features/ directory' }));
+            else
+                write('amendment traceability census: no features/ directory');
+            return 0;
+        }
+        const rowsOut = [];
+        for (const slug of slugs) {
+            try {
+                const r = checkOne(join(featuresDir, slug));
+                rowsOut.push({ slug, outcome: r.decision.outcome, counts: r.decision.counts, reasons: r.decision.reasons.length });
+            }
+            catch (err) {
+                // AM-6: one unreadable feature becomes its own row. Dropping it silently would make the
+                // census read like coverage it does not have.
+                rowsOut.push({ slug, outcome: 'read-error', error: err.message });
+            }
+        }
+        if (json) {
+            write(JSON.stringify({ ok: true, mode: 'all', note: AMENDMENT_VACUITY_NOTE, features: rowsOut }));
+        }
+        else {
+            const tally = new Map();
+            for (const r of rowsOut)
+                tally.set(String(r['outcome']), (tally.get(String(r['outcome'])) ?? 0) + 1);
+            for (const r of rowsOut) {
+                if (r['outcome'] !== 'pass' && r['outcome'] !== 'skip')
+                    write(`  [${String(r['outcome'])}] ${String(r['slug'])}`);
+            }
+            write(`amendment traceability census over ${rowsOut.length} feature(s): ${[...tally].map(([k, v]) => `${v} ${k}`).join(', ')}`);
+            write(AMENDMENT_VACUITY_NOTE);
+        }
+        return 0;
+    }
+    const explicitDir = (options.get('feature-dir') ?? '').trim();
+    const slug = (options.get('slug') ?? '').trim();
+    if (explicitDir === '' && slug === '') {
+        write('dz amendment-check: one of --slug / --feature-dir is required (or --all for a census)');
+        return 2;
+    }
+    const featureDir = explicitDir !== '' ? resolve(cwd, explicitDir) : join(cwd, 'features', slug);
+    const { decision, resolutions } = checkOne(featureDir);
+    if (json) {
+        write(JSON.stringify({
+            ok: decision.outcome === 'pass' || decision.outcome === 'skip',
+            slug: basename(featureDir),
+            outcome: decision.outcome,
+            exit: decision.exit,
+            counts: decision.counts,
+            reasons: decision.reasons,
+            rows: resolutions,
+            note: AMENDMENT_VACUITY_NOTE,
+        }));
+    }
+    else {
+        for (const r of resolutions) {
+            if (r.verdict !== 'resolved')
+                write(`  [${r.verdict}] ${r.id}${r.testId === null ? '' : ` \`${r.testId}\``} — ${r.detail}`);
+        }
+        write(AMENDMENT_VACUITY_NOTE);
+        // The verdict is the LAST line, in the K2 gate's own shape, so a caller that reads the tail of
+        // the output reads a verdict rather than a finding.
+        write(amendmentVerdictLine(decision));
+    }
+    return decision.exit;
+}
 function cmdFeatureAdrCheckpoint(options, flags, cwd, write) {
     const json = flags.has('json');
     const emit = (payload, human, code) => {
@@ -11513,6 +12171,10 @@ export async function runCli(argv, io = {}) {
                 return cmdEpochReplay(options, flags, cwd, write);
             case 'score':
                 return cmdScore(options, flags, cwd, write);
+            case 'feature-adr-record':
+                return cmdFeatureAdrRecord(options, flags, cwd, write);
+            case 'amendment-check':
+                return cmdAmendmentCheck(options, flags, cwd, write);
             case 'feature-adr-checkpoint':
                 return cmdFeatureAdrCheckpoint(options, flags, cwd, write);
             case 'reqe':