@dzhechkov/harness-cli 0.7.2 → 0.7.4

package/src/cli.ts

@@ -7,7 +7,8 @@
 import { appendFileSync, chmodSync, closeSync, cpSync, existsSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execFileSync, execSync, spawn, type ChildProcess } from 'node:child_process';
+import { KNOWN_CLI_FLAGS } from './known-flags.js';
+import { execFileSync, execSync, spawn, spawnSync, type ChildProcess } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import { homedir, tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
@@ -311,6 +312,33 @@ import {
   type WorkOrder,
   type EpochOutcome,
   scoreRun,
+  readQeGrade,
+  recapWindow,
+  decideHorizon,
+  withinWindow,
+  buildRecap,
+  renderRecap,
+  parseSourceManifest,
+  unknownFlagNotice,
+  mirrorWriterExplanation,
+  appendRecallUsage,
+  closenessLine,
+  anyAboveFloor,
+  decideNameCheck,
+  renderNameCheck,
+  exportedNamesIn,
+  dispatchedCommandsIn,
+  type NameFacts,
+  type NameQuery,
+  decideSourceProvenance,
+  renderSourceProvenance,
+  REFUSED_HORIZONS,
+  type RecapHorizon,
+  type RecapWindow,
+  type Delivery,
+  type Publish,
+  type GuardRun,
+  type ReuseFacts,
   renderScorecard,
   renderCompoundingReport,
   readReinforcementState,
@@ -466,6 +494,9 @@ 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 recap [--day|--week|--month] [--at <ISO date>] [--project <dir>] [--json]   (what was done over a window, from records only: deliveries with the grade an independent review STATED — a report naming two grades is reported ambiguous, never guessed — registry publishes, gate verdicts, knowledge reuse. --quarter/--half-year/--year are RECOGNISED and REFUSED with the real span in days: there is one complete quarter and the longest record is 174 days. Every section carries its own data-start date, and "the source was not read" never prints as zero. Contaminated measures — commit count, lines, tokens, learning-event volume, inventory counts, lesson count — are not computed, and the report says so. exit 0 reported / 2 refused)
+  dz name-check [--command <n>] [--module <basename>] [--export <a,b>] [--project <dir>] [--json]   (is this name free, BEFORE a line of code? Scans workspace SOURCE — never dist, because a stale build answers 'free' confidently. Checks a dz command name against the dispatcher AND the help block, a module basename against every package's src/, and exported identifiers against every declaration in the workspace. exit 0 all free / 1 at least one taken, naming where / 2 nothing asked or the scan did not run — an empty sweep is never a clean bill. Honest limit, printed on the passing path: it reads declarations, so a re-export under a different name stays the build's job)
+  dz provenance-check --manifest <sources.json> [--project <dir>] [--json]   (nothing goes out citing a source that may not leave this machine. Checks PROVENANCE, not words: every claim names its source, and only a KNOWN kind that resolves safely is cleared. Repo paths go through 'git -C <root> check-ignore' over the RESOLVED path — a symlink into an ignored directory is REFUSED (git classifies the string and never dereferences, MEASURED), and the verdict does not change with your working directory. Store records must be named in the git-TRACKED provenance-public.json, so declaring one public is a reviewable commit rather than a field inside an ignored store. An undeclared kind is refused, never inferred from the path's shape. exit 0 allowed / 1 blocked / 3 NOT ESTABLISHED — an empty manifest, an unreadable one, or an oracle that did not run is never a pass. It proves what was CITED: it cannot see a paraphrase with no citation, nor confidential text pasted by hand into an allowed file)
   dz amendment-check --slug <slug> | --feature-dir <dir> | --all [--json]   (the deterministic Step-8 amendment gate: every AM-N row must resolve to a test found INSIDE the file the row names; the PLAN is authoritative when it carries rows, and an ideation amendment the plan drops is a failure. exit 0 pass/skip, 1 fail, 3 NOT-ESTABLISHED — a section that parsed ZERO rows is never a pass. --all is a CENSUS and always exits 0. Does NOT prove non-vacuity — that is dz discrimination-check)
   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)
@@ -3458,8 +3489,47 @@ async function cmdRecall(options: Map<string, string>, flags: Set<string>, cwd:
     // might treat as a break — not just CR/LF. Round 4 forged the domain-boost note
     // twice over: once through `domain`, which was rendered raw, and once through a
     // U+2028 that Python's splitlines() honours and this replace did not.
-    const shown = oneLine(h.pattern.pattern).slice(0, 80);
-    write(`  [${h.pattern.reward.toFixed(2)}] (${oneLine(h.pattern.domain)})${backendTag}${qTag} ${shown}`);
+    // Closeness rides INSIDE the backend tag, and only when the semantic leg ran — the engine-less
+    // output stays byte-identical, which a pinned test asserts. Two axes, never merged: the leading
+    // number is the lesson's own reward ("what did this earn"), `sim` is closeness ("is it about
+    // what you asked"). The ▲/▽ marker is the floor comparison done for the reader, against the
+    // same measured per-language floors the recall hook already trusts.
+    const simTag = vectorOn ? ` ${closenessLine(h.similarity, shownQuery)}` : '';
+    const backendAndSim = vectorOn ? ` ⟨${h.backend}${simTag}⟩` : '';
+    // 160, not 80: at 80 characters the evidence a reader needs to judge relevance sits in the
+    // hidden remainder, and the cosine then appears to describe the visible fragment rather than
+    // the whole lesson. `--full` prints it all, still on one line.
+    const width = flags.has('full') ? Number.POSITIVE_INFINITY : 160;
+    const oneLined = oneLine(h.pattern.pattern);
+    const shown = width === Number.POSITIVE_INFINITY ? oneLined : oneLined.slice(0, width);
+    write(`  [${h.pattern.reward.toFixed(2)}] (${oneLine(h.pattern.domain)})${backendAndSim}${qTag} ${shown}`);
+  }
+  // The apply leg records itself. `dz recall` wrote NOTHING to the usage log — MEASURED 2026-08-24,
+  // 1106 rows before the call and 1106 after — so "how many lessons were recalled" was underivable,
+  // and the pipeline banner asserted a hardcoded `--recalled 3` at three call sites instead.
+  //
+  // Only hits with a MEASURED cosine are recorded. The log's `score` is defined as cosine relevance
+  // and its validator requires a finite number; writing an RRF rank there would mix two scales in
+  // one field, which is the exact lie the closeness work just removed from the display. The gap is
+  // printed rather than hidden, so an under-count can never read as "only these were read".
+  if (vectorOn && hits.length > 0) {
+    const measured = hits.filter((h) => typeof h.similarity === 'number' && Number.isFinite(h.similarity));
+    if (measured.length > 0) {
+      appendRecallUsage({
+        projectRoot: projectRoot,
+        query: shownQuery,
+        hits: measured.map((h) => ({ dzId: patternRecordId(h.pattern), score: h.similarity as number })),
+      });
+    }
+    if (measured.length < hits.length) {
+      write(`  ℹ ${measured.length} of ${hits.length} read(s) recorded — a hit with no measured closeness carries no score in a log whose score IS the cosine`);
+    }
+  }
+  if (vectorOn && hits.length > 0 && !anyAboveFloor(hits.map((h) => h.similarity), shownQuery)) {
+    // Said ONCE, in words, instead of leaving the reader to compare every number themselves. This
+    // is the difference between "a strong match" and "the best of a weak field", and without it a
+    // list of five ▽ rows reads exactly like a list of five answers.
+    write(`  ℹ nothing here clears the measured similarity floor for this query — this is the best of a weak field, not a match`);
   }
   if (sawQuarantined) {
     // The loop stays VISIBLE (ADR D2): a quarantined hit is shown, marked, and explained.
@@ -3592,7 +3662,11 @@ async function cmdVector(options: Map<string, string>, flags: Set<string>, cwd:
     // `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)'}`);
+    // The REASON comes from the same read that decided the state. It used to be one hardcoded
+    // sentence naming a single cause, so a project that set `memory.vector.engine: "off"` was
+    // told it lacked `memory.backend=agentdb` — a diagnosis pointing at something that was not
+    // broken (MEASURED 2026-08-24).
+    write(`  Mirror writer: ${st.mirrorWriterEnabled ? 'ON' : 'OFF'} (${mirrorWriterExplanation(st.mirrorWriterState)})`);
     // "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.
@@ -9477,6 +9551,463 @@ function extractIntoTempDir(packDir: string, tmp: string): { dir: string; cleanu
   return { dir: join(tmp, 'package'), cleanup: (): void => { try { rmSync(tmp, { recursive: true, force: true }); } catch { /* best-effort */ } } };
 }
 
+// ── `dz recap` (feature dz-recap) ────────────────────────────────────────────
+//
+// What was done over a day, a week or a month — and a loud refusal for anything longer, because the
+// data does not reach. All the pure decisions live in harness-core/src/recap.ts; this half only
+// gathers facts, and every gathering step below carries the measurement that shaped it (see
+// features/dz-recap/03.5_ideation_report.md).
+
+/** Feature-dir creation dates in ONE git pass. MEASURED: 0.099s here against 10.171s per-dir. */
+function recapGitCreations(repo: string): { dates: Map<string, string>; ok: boolean } {
+  const dates = new Map<string, string>();
+  let out: string;
+  try {
+    out = execFileSync('git', ['log', '--diff-filter=A', '--name-only', '--format=%aI', '--', 'features/'], {
+      cwd: repo, encoding: 'utf-8', maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch {
+    return { dates, ok: false };
+  }
+  let commitIso = '';
+  for (const raw of out.split('\n')) {
+    const line = raw.trim();
+    if (line === '') continue;
+    if (!line.startsWith('features/')) { commitIso = line; continue; }
+    if (commitIso === '') continue;
+    const parts = line.split('/');
+    // `features/` also holds loose .md files committed directly into it — 5 of them, measured. A
+    // naive parts[1] would file each of those as a slug.
+    if (parts.length < 3) continue;
+    // git walks newest to oldest, so the LAST write per slug is its creation. Taking the min of the
+    // date STRINGS is wrong when commits carry different UTC offsets (reproduced on alpha-to-rc:
+    // string-min picked 07:06:49+00:00 over 08:00:40+03:00, which is 05:00:40Z and earlier).
+    dates.set(parts[1] as string, commitIso);
+  }
+  return { dates, ok: true };
+}
+
+function recapDeliveries(repo: string, write: Write): { facts: { dataStart: string | null; items: Delivery[] } | null; uncommitted: string[] } {
+  const featuresDir = join(repo, 'features');
+  if (!existsSync(featuresDir)) return { facts: null, uncommitted: [] };
+  const { dates, ok } = recapGitCreations(repo);
+  if (!ok) {
+    write('dz recap: git log unavailable — the deliveries section cannot be read');
+    return { facts: null, uncommitted: [] };
+  }
+  // Scoped to the TOP-LEVEL features/ only. Six worktrees are live in this repo and one carries its
+  // own diverged .dz store; a recursive walk would merge two chronologies.
+  const onDisk = readdirSync(featuresDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+  const items: Delivery[] = [];
+  const uncommitted: string[] = [];
+  for (const slug of onDisk) {
+    const created = dates.get(slug);
+    if (created === undefined) { uncommitted.push(slug); continue; }
+    const reportPath = join(featuresDir, slug, '08_qe_report.md');
+    if (!existsSync(reportPath)) { items.push({ slug, createdIso: created, gradeStatus: 'no-report', grade: null }); continue; }
+    let reading: { status: 'unique' | 'ambiguous' | 'none'; grade: string | null };
+    try { reading = readQeGrade(readFileSync(reportPath, 'utf-8')); } catch { reading = { status: 'none', grade: null }; }
+    // `Delivery` is a discriminated union: `unique` MUST carry a grade, everything else MUST carry
+    // null. Narrowing here is what keeps "graded" and "we have a grade" the same statement.
+    items.push(reading.status === 'unique' && typeof reading.grade === 'string'
+      ? { slug, createdIso: created, gradeStatus: 'unique', grade: reading.grade }
+      : { slug, createdIso: created, gradeStatus: reading.status === 'unique' ? 'none' : reading.status, grade: null });
+  }
+  const starts = [...dates.values()].sort();
+  return { facts: { dataStart: starts.length > 0 ? (starts[0] as string).slice(0, 10) : null, items }, uncommitted };
+}
+
+/** Read a JSONL store defensively: BOTH stores grew fields over time, with no schema marker. */
+function recapReadJsonl(path: string): Record<string, unknown>[] | null {
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path, 'utf-8').split('\n').filter((l) => l.trim() !== '').flatMap((l) => {
+      try { return [JSON.parse(l) as Record<string, unknown>]; } catch { return []; }
+    });
+  } catch {
+    return null;
+  }
+}
+
+function recapGuard(repo: string): { dataStart: string | null; items: GuardRun[] } | null {
+  const rows = recapReadJsonl(join(repo, '.dz', 'guard-audit.jsonl'));
+  if (rows === null) return null;
+  const items: GuardRun[] = [];
+  for (const r of rows) {
+    const iso = typeof r['ts'] === 'string' ? r['ts'] : null;
+    if (iso === null) continue;
+    const violations = Array.isArray(r['violations']) ? (r['violations'] as Record<string, unknown>[]) : [];
+    const rules = violations.map((v) => (typeof v['rule'] === 'string' ? v['rule'] : '')).filter((s) => s !== '');
+    items.push({ iso, verdict: typeof r['verdict'] === 'string' ? r['verdict'] : 'unknown', rules });
+  }
+  const sorted = items.map((i) => i.iso).sort();
+  return { dataStart: sorted.length > 0 ? (sorted[0] as string).slice(0, 10) : null, items };
+}
+
+/** Probe rows that join to no lesson. Measured: `teach:zzz` and `teach:probe` are test pollution. */
+const RECAP_PROBE_IDS: ReadonlySet<string> = new Set(['teach:zzz', 'teach:probe']);
+
+function recapReuse(repo: string, window: RecapWindow): ReuseFacts | null {
+  const rows = recapReadJsonl(join(repo, '.dz', 'recall-usage.jsonl'));
+  if (rows === null) return null;
+  const recalled = new Set<string>();
+  let eventsInWindow = 0;
+  let earliest: string | null = null;
+  for (const r of rows) {
+    const iso = typeof r['ts'] === 'string' ? r['ts'] : null;
+    const id = typeof r['dzId'] === 'string' ? r['dzId'] : null;
+    if (iso === null || id === null || RECAP_PROBE_IDS.has(id)) continue;
+    if (earliest === null || iso < earliest) earliest = iso;
+    recalled.add(id);
+    if (withinWindow(window, iso)) eventsInWindow++;
+  }
+  let lessonsTotal = 0;
+  try { lessonsTotal = loadStorePatternsSync(repo).length; } catch { lessonsTotal = 0; }
+  return {
+    dataStart: earliest === null ? null : earliest.slice(0, 10),
+    eventsInWindow,
+    lessonsEverRecalled: recalled.size,
+    lessonsTotal,
+  };
+}
+
+/** Publishes come from a cache ONLY. 51 packages cost 18.3s over the network — never inside a report. */
+function recapPublishes(repo: string): { dataStart: string | null; items: Publish[] } | null {
+  const path = join(repo, '.dz', 'recap', 'npm-times.json');
+  if (!existsSync(path)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf-8')) as { packages?: Record<string, { versions?: Record<string, string> }> };
+    const items: Publish[] = [];
+    for (const [pkg, entry] of Object.entries(raw.packages ?? {})) {
+      for (const [version, iso] of Object.entries(entry.versions ?? {})) {
+        if (version === 'created' || version === 'modified') continue;
+        items.push({ pkg, version, iso });
+      }
+    }
+    const sorted = items.map((i) => i.iso).sort();
+    return { dataStart: sorted.length > 0 ? (sorted[0] as string).slice(0, 10) : null, items };
+  } catch {
+    return null;
+  }
+}
+
+// ── `dz provenance-check` (feature provenance-gate) ──────────────────────────
+//
+// Nothing goes out citing a source that may not leave this machine. The decisions are pure and live
+// in harness-core/src/provenance.ts; this half runs the oracle, and every step below carries the
+// measurement that shaped it (features/provenance-gate/03.5_ideation_report.md).
+
+/** The tracked file that declares which store records may be cited. Tracked ON PURPOSE (ADR-001). */
+const PROVENANCE_PUBLIC_REL = 'provenance-public.json';
+
+/**
+ * Resolve one source path, and refuse anything that lands outside the repository.
+ *
+ * `realpathSync` is the point: `git check-ignore` classifies the STRING and never dereferences a
+ * symlink, so `allowed/pointer.md → ../secret/note.md` came back "not ignored" while `cat` printed
+ * the secret (MEASURED 2026-08-22 in a clean temp repo). Classifying the resolved target closes it.
+ */
+function provenanceResolve(repoRoot: string, source: string): string | null {
+  try {
+    const abs = isAbsolute(source) ? source : join(repoRoot, source);
+    const real = realpathSync(abs);
+    const rootReal = realpathSync(repoRoot);
+    // `startsWith` alone would accept a sibling directory whose name merely extends the root's.
+    if (real !== rootReal && !real.startsWith(rootReal + sep)) return null;
+    return real;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ask git which of these paths are ignored — ONE batch call, and `null` when it did not run.
+ *
+ * Two measured hazards, both closed here:
+ *  - `git check-ignore` resolves a relative path against the PROCESS CWD, so the same manifest that
+ *    blocked from the repo root cleared everything from a subdirectory, with no error and no
+ *    non-zero exit. Always `git -C <root>`, and always absolute paths.
+ *  - one out-of-repo path anywhere in the batch prints the matches found so far and then dies with
+ *    exit 128, dropping every path queued behind it. So callers must filter those out first, and
+ *    any exit outside {0,1} is an ORACLE FAILURE for the whole batch, never partial credit.
+ */
+const PROVENANCE_CANARY = 'dz-provenance-canary';
+
+/**
+ * Prove the oracle actually answers before believing its silence.
+ *
+ * `git check-ignore` returns exit 1 for "none of these are ignored" — which is indistinguishable
+ * from a `git` on PATH that does nothing and exits 1, and that reading clears EVERY path
+ * (cross-family review, codex `gpt-5.6-sol`, 2026-08-22). So each run first asks a question whose
+ * answer is known: a canary name made ignorable through a private excludes file. A real git says
+ * "ignored"; anything that cannot is not a usable oracle.
+ *
+ * The private excludes file is passed only on THIS call, so it cannot alter a real verdict —
+ * verified by running: with the canary file supplied, `README.md` is still not ignored.
+ */
+function provenanceOracleAlive(repoRoot: string): boolean {
+  let excludes = '';
+  try {
+    excludes = join(mkdtempSync(join(tmpdir(), 'dz-prov-canary-')), 'excludes');
+    writeFileSync(excludes, `${PROVENANCE_CANARY}\n`);
+    const probe = spawnSync('git', ['-C', repoRoot, '-c', `core.excludesFile=${excludes}`, 'check-ignore', '-q', PROVENANCE_CANARY], { encoding: 'utf-8' });
+    return probe.error === undefined && probe.status === 0;
+  } catch {
+    return false;
+  } finally {
+    try { if (excludes !== '') rmSync(dirname(excludes), { recursive: true, force: true }); } catch { /* best-effort */ }
+  }
+}
+
+function provenanceIgnored(repoRoot: string, absPaths: readonly string[]): Set<string> | null {
+  if (!provenanceOracleAlive(repoRoot)) return null;
+  if (absPaths.length === 0) return new Set();
+  // `-z` on BOTH sides. Without it a path containing a NEWLINE splits into two records, and the
+  // gate answers about a path nobody asked about — a filename may legally contain a newline on
+  // Linux, and one was constructed to prove it (cross-family review, 2026-08-22).
+  const res = spawnSync('git', ['-C', repoRoot, 'check-ignore', '-z', '--stdin', '--no-index'], {
+    input: `${absPaths.join('\0')}\0`,
+    encoding: 'utf-8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  // 0 = at least one ignored, 1 = none ignored. Anything else (128 fatal, a signal, a missing git)
+  // means the question was not answered, and an unanswered question is not an all-clear.
+  if (res.error !== undefined || res.status === null || (res.status !== 0 && res.status !== 1)) return null;
+  return new Set((res.stdout ?? '').split('\0').filter((l: string) => l !== ''));
+}
+
+function cmdProvenanceCheck(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const repoRoot = resolve(options.get('project') ?? cwd);
+  const json = flags.has('json');
+  const manifestPath = (options.get('manifest') ?? '').trim();
+  if (manifestPath === '') {
+    write('dz provenance-check: --manifest <sources.json> is required');
+    return 2;
+  }
+
+  let manifest: ReturnType<typeof parseSourceManifest> = null;
+  try {
+    // The manifest path is the USER's, so it resolves against the CWD they typed it in — not
+    // against --project, which names the repository the sources belong to. Resolving it against
+    // the repo root made `--manifest ../sources.json --project ..` read a file outside the tree
+    // and report NOT ESTABLISHED for a manifest that was right there.
+    manifest = parseSourceManifest(readFileSync(resolve(cwd, manifestPath), 'utf-8'));
+  } catch {
+    manifest = null;
+  }
+
+  // The public-records list is read from a GIT-TRACKED, COMMITTED file, so declaring a record public
+  // is an act that shows up in a diff someone reviewed. Round 2 of the cross-family review found the
+  // first version calling the file "tracked" and never checking it: an untracked file the drafting
+  // process wrote itself cleared any record it liked, and the whole review argument collapsed.
+  //
+  // Both halves are load-bearing. TRACKED alone is not enough — a tracked file with uncommitted
+  // edits has been through no review either.
+  const publicRecords = new Set<string>();
+  let listUntrusted: string | null = null;
+  if (existsSync(join(repoRoot, PROVENANCE_PUBLIC_REL))) {
+    // Read the COMMITTED blob, never the working copy. Round 5 of the cross-family review found the
+    // list guarded by `git status`, which `--assume-unchanged` blinds — the same bypass already
+    // closed for cited paths, left open one file away. Reading `HEAD:<path>` removes the question
+    // instead of answering it: the gate sees exactly what was reviewed, whatever sits on disk.
+    const show = spawnSync('git', ['-C', repoRoot, 'show', `HEAD:${PROVENANCE_PUBLIC_REL}`], { encoding: 'utf-8', maxBuffer: 8 * 1024 * 1024 });
+    if (show.error !== undefined || show.status !== 0) {
+      listUntrusted = `${PROVENANCE_PUBLIC_REL} is not committed, so nothing in it was ever reviewed — a record cannot be cleared by a list the drafting process could have written itself`;
+    } else {
+      try {
+        const raw = JSON.parse(show.stdout ?? '') as { records?: unknown };
+        if (Array.isArray(raw.records)) for (const r of raw.records) if (typeof r === 'string') publicRecords.add(r);
+      } catch {
+        listUntrusted = `the committed ${PROVENANCE_PUBLIC_REL} could not be parsed`;
+      }
+    }
+  }
+  // A list that exists but cannot be trusted is NOT the same as no list: the operator plainly meant
+  // to use it. Silently emptying it would refuse records for a reason that names the wrong problem.
+  if (listUntrusted !== null) {
+    const dead = { outcome: 'not-established' as const, exit: 3 as const, claims: [], reason: listUntrusted };
+    if (json) write(JSON.stringify(dead));
+    else for (const line of renderSourceProvenance(dead)) write(line);
+    return 3;
+  }
+
+  const resolved = new Map<string, string | null>();
+  const toAsk: string[] = [];
+  for (const c of manifest?.claims ?? []) {
+    if (c.kind !== 'path' || typeof c.source !== 'string' || c.source.trim() === '') continue;
+    const src = c.source.trim();
+    if (resolved.has(src)) continue;
+    const real = provenanceResolve(repoRoot, src);
+    resolved.set(src, real);
+    if (real !== null) toAsk.push(real);   // out-of-repo paths NEVER reach the batch call
+  }
+
+  // Three questions, not one: ignored (refused by the owner), tracked (reviewed at all), and clean
+  // (reviewed in its CURRENT state). A file the drafting process wrote a second ago answers "no" to
+  // the first and would have been cleared by a gate that only asked it.
+  const tracked = new Set<string>();
+  const dirty = new Set<string>();
+  if (toAsk.length > 0) {
+    const ls = spawnSync('git', ['-C', repoRoot, 'ls-files', '-z', '--', ...toAsk], { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 });
+    if (ls.error === undefined && ls.status === 0) {
+      for (const rel of (ls.stdout ?? '').split('\0')) if (rel !== '') tracked.add(resolve(repoRoot, rel));
+    }
+    // "Clean" is decided by CONTENT, not by `git status`. MEASURED 2026-08-22: after
+    // `git update-index --assume-unchanged cited.md`, replacing the file's contents outright leaves
+    // `git status --porcelain` EMPTY, so a status-based check clears a file whose bytes no longer
+    // match anything anyone reviewed (cross-family review round 4). Comparing the blob hash on disk
+    // against the one in HEAD sees the swap; it also subsumes staged-but-uncommitted.
+    // `--no-filters` is not a detail. A `.gitattributes` clean filter runs on hash-object, so a
+    // filter that strips content makes a modified file hash IDENTICAL to its committed blob —
+    // MEASURED 2026-08-22: with `filter.strip.clean = head -c 7`, appending confidential text left
+    // the hash unchanged (round 6). We compare the bytes on disk, not the bytes git would store.
+    const onDisk = spawnSync('git', ['-C', repoRoot, 'hash-object', '--no-filters', '--', ...toAsk], { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 });
+    const inHead = spawnSync('git', ['-C', repoRoot, 'ls-tree', '-z', 'HEAD', '--', ...toAsk], { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 });
+    if (onDisk.error !== undefined || onDisk.status !== 0 || inHead.error !== undefined || inHead.status !== 0) {
+      // Cannot compare ⇒ cannot clear. Every candidate is treated as unreviewed rather than clean.
+      for (const p of toAsk) dirty.add(p);
+    } else {
+      const diskHashes = (onDisk.stdout ?? '').split('\n').map((l: string) => l.trim()).filter((l: string) => l !== '');
+      const headHash = new Map<string, string>();
+      for (const rec of (inHead.stdout ?? '').split('\0')) {
+        if (rec === '') continue;
+        const tab = rec.indexOf('\t');
+        if (tab < 0) continue;
+        const parts = rec.slice(0, tab).split(/\s+/);
+        headHash.set(resolve(repoRoot, rec.slice(tab + 1)), parts[2] ?? '');
+      }
+      toAsk.forEach((abs, i) => {
+        const committed = headHash.get(abs);
+        if (committed === undefined || committed !== diskHashes[i]) dirty.add(abs);
+      });
+    }
+  }
+
+  const decision = decideSourceProvenance(manifest, {
+    ignoredPaths: provenanceIgnored(repoRoot, toAsk),
+    publicRecords,
+    resolved,
+    trackedPaths: tracked,
+    dirtyPaths: dirty,
+  });
+
+  if (json) write(JSON.stringify(decision));
+  else for (const line of renderSourceProvenance(decision)) write(line);
+  return decision.exit;
+}
+
+// ── `dz name-check` (feature name-check) ─────────────────────────────────────
+//
+// Is this name free, before a line of code is written? Twice in one day a collision broke the build
+// outright — `dz retro` was already a command, `decideProvenance` already an export — and both were
+// answerable in advance. The decisions are pure and live in harness-core/src/name-check.ts; this half
+// scans the workspace SOURCE, never `dist` (ADR-001: a stale build answers "free" confidently).
+
+function nameCheckScan(repoRoot: string): NameFacts {
+  const pkgsRoot = join(repoRoot, 'packages', '@dzhechkov');
+  if (!existsSync(pkgsRoot)) return { commands: new Set(), modules: new Map(), exports: new Map(), scanFailed: true };
+  const commands = new Set<string>();
+  const modules = new Map<string, string>();
+  const exportsFound = new Map<string, string>();
+  let files = 0;
+  let packages = 0;
+  try {
+    for (const pkg of readdirSync(pkgsRoot, { withFileTypes: true })) {
+      if (!pkg.isDirectory()) continue;
+      const srcDir = join(pkgsRoot, pkg.name, 'src');
+      if (!existsSync(srcDir)) continue;
+      packages++;
+      for (const f of readdirSync(srcDir, { withFileTypes: true })) {
+        if (!f.isFile() || !f.name.endsWith('.ts') || f.name.endsWith('.d.ts')) continue;
+        const rel = `${pkg.name}/src/${f.name}`;
+        const base = f.name.replace(/\.ts$/, '');
+        if (!modules.has(base)) modules.set(base, rel);
+        const text = readFileSync(join(srcDir, f.name), 'utf-8');
+        files++;
+        // Prefer the file that DECLARES a name over an `index.ts` that merely re-exports it: the
+        // author needs to know where to look, and "it is in index.ts" points at the wiring, not the
+        // owner. First writer wins otherwise, so a barrel scanned first would hide every source.
+        for (const n of exportedNamesIn(text)) {
+          const known = exportsFound.get(n);
+          if (known === undefined || (known.endsWith('/index.ts') && f.name !== 'index.ts')) exportsFound.set(n, rel);
+        }
+        // Command names come from the dispatcher AND from the help block: a name that dispatches but
+        // is undocumented is still taken, and so is the reverse.
+        if (f.name === 'cli.ts') {
+          for (const c of dispatchedCommandsIn(text)) commands.add(c);
+          const help = /^\s{2}dz ([a-z][a-z0-9-]*)/gm;
+          for (let m = help.exec(text); m !== null; m = help.exec(text)) if (m[1] !== undefined) commands.add(m[1]);
+        }
+      }
+    }
+  } catch {
+    return { commands: new Set(), modules: new Map(), exports: new Map(), scanFailed: true };
+  }
+  // A scan that read nothing is not a scan. Reporting "free" off an empty sweep is the same defect
+  // as a gate that passes because it never ran. What the sweep SAW travels with the facts, so the
+  // operator can see whether it looked at a workspace or at a directory of the right shape.
+  if (files === 0) return { commands: new Set(), modules: new Map(), exports: new Map(), scanFailed: true };
+  return { commands, modules, exports: exportsFound, scanned: { packages, files, exports: exportsFound.size, commands: commands.size } };
+}
+
+function cmdNameCheck(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const repoRoot = resolve(options.get('project') ?? cwd);
+  const json = flags.has('json');
+  const queries: NameQuery[] = [];
+  const push = (kind: NameQuery['kind'], raw: string | undefined): void => {
+    for (const n of (raw ?? '').split(',').map((s) => s.trim()).filter((s) => s !== '')) queries.push({ kind, name: n });
+  };
+  push('command', options.get('command'));
+  push('module', options.get('module'));
+  push('export', options.get('export'));
+
+  const facts = nameCheckScan(repoRoot);
+  const decision = decideNameCheck(queries, facts);
+  if (json) write(JSON.stringify(decision));
+  else for (const line of renderNameCheck(decision, facts.scanned)) write(line);
+  return decision.exit;
+}
+
+function cmdRecap(options: Map<string, string>, flags: Set<string>, cwd: string, write: Write): number {
+  const repo = resolve(options.get('project') ?? cwd);
+  const json = flags.has('json');
+
+  // Every horizon is RECOGNISED, including the refused ones — swallowing `--year` silently would be
+  // the same defect as a gate that passes because it never ran.
+  const asked = (['day', 'week', 'month', ...REFUSED_HORIZONS] as const).filter((h) => flags.has(h));
+  if (asked.length > 1) { write(`dz recap: pick ONE horizon, not ${asked.length}`); return 2; }
+  const requested = asked[0] ?? 'week';
+
+  const at = (options.get('at') ?? new Date().toISOString()).trim();
+  if (!/^\d{4}-\d{2}-\d{2}/.test(at)) { write(`dz recap: --at must be an ISO date (YYYY-MM-DD), got ${JSON.stringify(at)}`); return 2; }
+
+  const deliveries = recapDeliveries(repo, write);
+  const guard = recapGuard(repo);
+  const publishes = recapPublishes(repo);
+  const starts = [deliveries.facts?.dataStart, guard?.dataStart, publishes?.dataStart]
+    .filter((d): d is string => typeof d === 'string').sort();
+  const spanDays = starts.length === 0 ? 0
+    : Math.max(0, Math.round((Date.parse(`${at.slice(0, 10)}T00:00:00Z`) - Date.parse(`${starts[0] as string}T00:00:00Z`)) / 86_400_000));
+
+  const decision = decideHorizon({ requested, spanDays });
+  if (decision.action === 'refuse') {
+    if (json) write(JSON.stringify({ ok: false, requested, spanDays, reason: decision.reason }));
+    else write(`dz recap: REFUSED — ${decision.reason}`);
+    return 2;
+  }
+
+  const window = recapWindow(requested as RecapHorizon, at);
+  const report = buildRecap({
+    window, spanDays,
+    deliveries: deliveries.facts, publishes, guard,
+    reuse: recapReuse(repo, window),
+    uncommittedSlugs: deliveries.uncommitted.sort(),
+  });
+  if (json) write(JSON.stringify(report));
+  else for (const line of renderRecap(report)) write(line);
+  return 0;
+}
+
 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;
@@ -9574,15 +10105,14 @@ function cmdAmendmentCheck(options: Map<string, string>, flags: Set<string>, cwd
     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);
+    // A missing ideation report must NOT stop the plan from being read. It did: an S/M feature that
+    // legitimately skips Step 3.5 got `skip — no Amendments section` while its plan carried a
+    // complete section, and the same split produced verdicts that contradicted their own counts
+    // (rows parsed from the PLAN, `sectionPresent` computed from the IDEATION report). MEASURED
+    // 2026-08-24 on features/name-check: resolved 0 with 3 rows sitting in the plan.
+    const sectionPresent = (ideation !== null && amendmentSection(ideation) !== null)
+      || (plan !== null && amendmentSection(plan) !== null);
+    const ideationRows = ideation === null ? [] : 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
@@ -12337,6 +12867,16 @@ export async function runCli(argv: string[], io: CliIo = {}): Promise<number> {
   };
   const { command, options, optionLists, flags } = parseArgs(argv);
 
+  // An unrecognised `--flag` must not pass in silence. MEASURED 2026-08-24: `dz recall "x" --breif
+  // --limit 2` printed the full ordinary output and exited 0, so a typo read as "the mode worked".
+  // It WARNS rather than refuses, and the reason is measured, not cautious: 53 of the names this CLI
+  // reads appear nowhere in help, and static extraction over the dispatch table lost `--week` from
+  // `dz recap` — a refusal built on either list would reject working commands, which is a worse
+  // failure than the one being fixed. Goes to STDERR so a `--json` consumer's stdout stays clean.
+  for (const notice of unknownFlagNotice([...flags, ...options.keys()].filter((k) => !k.startsWith('_positional_')), KNOWN_CLI_FLAGS)) {
+    writeErr(notice.line);
+  }
+
   // ── `dz --version` / `dz -v` / `dz version` — PRE-DISPATCH, before the help branch ──
   //
   // Until now `dz --version` printed the whole USAGE manual and exited 0 (MEASURED 2026-08-17,
@@ -12487,6 +13027,12 @@ 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 'recap':
+        return cmdRecap(options, flags, cwd, write);
+      case 'name-check':
+        return cmdNameCheck(options, flags, cwd, write);
+      case 'provenance-check':
+        return cmdProvenanceCheck(options, flags, cwd, write);
       case 'feature-adr-record':
         return cmdFeatureAdrRecord(options, flags, cwd, write);
       case 'amendment-check':