@dzhechkov/harness-cli 0.6.0 → 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,
@@ -400,7 +402,21 @@ import {
   parseBundle,
   planImport,
   decideCheckpointWrite,
+  amendmentSection,
+  planSaysNoAmendments,
+  parseAmendments,
+  resolveAmendments,
+  decideAmendmentOutcome,
+  amendmentVerdictLine,
+  amendmentsMissingFromPlan,
+  AMENDMENT_VACUITY_NOTE,
+  decideSignableSet,
+  signableSetLine,
+  decideRecordWrite,
+  decideReadBack,
+  recordVerdictLine,
 } from '@dzhechkov/harness-core';
+import type { RecordKind, RecordDecision } from '@dzhechkov/harness-core';
 import type { MutationEntryResult, MutationObservation, MutationRegistryEntry } from '@dzhechkov/harness-core';
 import type { SkillApplyFailure, SkillLoadFailure } from '@dzhechkov/harness-core';
 import type { ReqeDebt } from '@dzhechkov/harness-core';
@@ -450,6 +466,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)
@@ -2664,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
@@ -3066,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
@@ -3212,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})`);
@@ -3223,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;
   }
 
@@ -3250,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
@@ -3262,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
@@ -3271,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.
@@ -3280,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) {
@@ -3290,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) {
@@ -3331,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;
 }
 
 /* ------------------------------------------------------------------ */
@@ -3419,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;
   }
 
@@ -4548,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.
@@ -4587,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,
@@ -4597,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,
@@ -4615,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]++;
@@ -4631,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;
@@ -4719,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;
@@ -4749,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}`);
@@ -4791,7 +5064,7 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
   // 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)) {
@@ -4922,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;
         }
@@ -4941,7 +5216,75 @@ function cmdPublish(options: Map<string, string>, flags: Set<string>, cwd: strin
     }
   }
 
-  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: 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.
+      //
+      // 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`);
@@ -6392,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}`);
@@ -6447,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 {
@@ -6594,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 {
@@ -8958,6 +9354,260 @@ function scanOneReqeRoot(
  * 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: 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;
+  const stage = (options.get('stage') ?? '').trim();
+  const slug = (options.get('slug') ?? '').trim();
+  const payloadRaw = options.get('row') ?? options.get('pair') ?? '';
+
+  const emit = (d: RecordDecision, extra: Record<string, unknown> = {}): number => {
+    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 as NodeJS.ErrnoException).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 as Error).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 as Error).message}`, blocking: false, line: null });
+  }
+
+  // ADR-002: the write is verified against the disk, never inferred from the absence of an error.
+  let lastLine: string | null = null;
+  try {
+    const body = readFileSync(target, 'utf-8');
+    const lines = body.split('\n').filter((l) => l !== '');
+    lastLine = lines.length > 0 ? (lines[lines.length - 1] as string) : null;
+  } catch {
+    lastLine = null;
+  }
+  return emit(decideReadBack(decision.line, lastLine), { target });
+}
+
+function cmdAmendmentCheck(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const json = flags.has('json');
+  const readOr = (abs: string): string | null => {
+    try {
+      return readFileSync(abs, 'utf-8');
+    } catch {
+      return null;
+    }
+  };
+
+  const checkOne = (featureDir: string): { decision: ReturnType<typeof decideAmendmentOutcome>; resolutions: ReturnType<typeof resolveAmendments>; slug: string } => {
+    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: string[] = [];
+    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: Record<string, unknown>[] = [];
+    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 as Error).message });
+      }
+    }
+    if (json) {
+      write(JSON.stringify({ ok: true, mode: 'all', note: AMENDMENT_VACUITY_NOTE, features: rowsOut }));
+    } else {
+      const tally = new Map<string, number>();
+      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: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
   const json = flags.has('json');
   const emit = (payload: Record<string, unknown>, human: string, code: number): number => {
@@ -11775,6 +12425,10 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
         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':