@dzhechkov/harness-core 0.7.2 → 0.7.3

package/src/name-check.ts

@@ -0,0 +1,331 @@
+/**
+ * `dz name-check` — is this name free, before a line of code is written?
+ *
+ * WHY THIS EXISTS, stated plainly: twice in one day a name collision broke the build outright.
+ * `dz retro` was already a command (the per-session process retro), and its star re-export clash
+ * stopped the CLI from importing at all; `decideProvenance` was already an export (npm provenance),
+ * and the build went red mid-feature. MEASURED 2026-08-24: `case 'retro':` is in the dispatcher, and
+ * both `buildRetro` and `decideProvenance` are in the core's 1020-name public surface — so BOTH were
+ * answerable before any code, and nobody asked.
+ *
+ * The owner's question was "what guarantees you will check?". An agent's intention is layer 4 on this
+ * project's cost-of-detection ladder: it works while remembered and is silent when it lapses. A
+ * command is the guarantee; a promise is not.
+ *
+ * PURE: no filesystem here. The scan runs in the CLI and arrives as facts — see ADR-001 for why
+ * those facts come from SOURCE and never from `dist`.
+ */
+
+/** What kind of name was asked about. */
+export type NameKind = 'command' | 'module' | 'export';
+
+export interface NameQuery {
+  readonly kind: NameKind;
+  readonly name: string;
+}
+
+export interface NameFacts {
+  /** Command names found in the dispatcher and in the help block. */
+  readonly commands: ReadonlySet<string>;
+  /** Module basenames found as `src/<basename>.ts` in any workspace package. */
+  readonly modules: ReadonlyMap<string, string>;
+  /** Exported identifiers found by scanning SOURCE, mapped to the file that declares them. */
+  readonly exports: ReadonlyMap<string, string>;
+  /**
+   * True when the scan itself could not be performed (no workspace found, unreadable tree).
+   * A scan that did not run must never report "free" — that is the whole failure this command
+   * exists to prevent, one level up.
+   */
+  readonly scanFailed?: boolean;
+  /**
+   * What the sweep actually saw. Reported to the operator, because "one empty .ts file in a
+   * lookalike directory" and "the real workspace" both used to satisfy a bare did-it-open-a-file
+   * test, and the second question a reviewer asked was exactly that (2026-08-24).
+   */
+  readonly scanned?: { readonly packages: number; readonly files: number; readonly exports: number; readonly commands: number };
+}
+
+export type NameVerdict = 'free' | 'taken';
+
+export interface NameResolution {
+  readonly kind: NameKind;
+  readonly name: string;
+  readonly verdict: NameVerdict;
+  /** Where the collision lives, when there is one. Empty for a free name. */
+  readonly where: string;
+}
+
+export type NameOutcome = 'free' | 'taken' | 'not-established';
+
+export interface NameDecision {
+  readonly outcome: NameOutcome;
+  /** 0 every name free · 1 at least one taken · 2 nothing asked or the scan did not run. */
+  readonly exit: 0 | 1 | 2;
+  readonly results: readonly NameResolution[];
+  readonly reason: string;
+}
+
+/** Is a proposed name already spoken for? */
+export function classifyName(query: NameQuery, facts: NameFacts): NameResolution {
+  const name = query.name.trim();
+  const at = (verdict: NameVerdict, where: string): NameResolution => ({ kind: query.kind, name, verdict, where });
+  if (query.kind === 'command') {
+    return facts.commands.has(name) ? at('taken', 'already dispatched as a dz command') : at('free', '');
+  }
+  if (query.kind === 'module') {
+    const file = facts.modules.get(name);
+    return file === undefined ? at('free', '') : at('taken', file);
+  }
+  const file = facts.exports.get(name);
+  return file === undefined ? at('free', '') : at('taken', file);
+}
+
+/**
+ * The whole verdict.
+ *
+ * Two ways to be not-established, and neither returns zero: nothing was asked, or the scan did not
+ * run. "I checked nothing" and "nothing is taken" are different answers, and a gate that conflates
+ * them is green exactly when it is blind — the defect measured on `dz sync` (0/0, exit 0) and on the
+ * source scanner that printed `github: 0` for a 401.
+ */
+export function decideNameCheck(queries: readonly NameQuery[], facts: NameFacts): NameDecision {
+  if (facts.scanFailed === true) {
+    return { outcome: 'not-established', exit: 2, results: [], reason: 'the workspace could not be scanned, so no name was checked — this is not a clean bill' };
+  }
+  const asked = queries.filter((q) => q.name.trim() !== '');
+  if (asked.length === 0) {
+    return { outcome: 'not-established', exit: 2, results: [], reason: 'no name was asked about — pass --command, --module or --export' };
+  }
+  // ESTABLISHMENT IS PER KIND. A question about an export cannot be answered by a sweep that found
+  // no exports at all; a question about a command cannot be answered without having seen a CLI. A
+  // sweep of a lookalike tree satisfies neither, and the honest verdict there is "not established",
+  // not "free".
+  const unanswerable = asked.filter((q) => {
+    if (q.kind === 'command') return facts.commands.size === 0;
+    if (q.kind === 'module') return facts.modules.size === 0;
+    return facts.exports.size === 0;
+  });
+  if (unanswerable.length > 0) {
+    const kinds = [...new Set(unanswerable.map((q) => q.kind))].join(', ');
+    return {
+      outcome: 'not-established',
+      exit: 2,
+      results: [],
+      reason: `the sweep found nothing of kind: ${kinds} — a tree with no ${kinds} cannot answer a question about one, and reporting "free" from it would be a clean bill from an empty room`,
+    };
+  }
+  const results = asked.map((q) => classifyName(q, facts));
+  const taken = results.filter((r) => r.verdict === 'taken');
+  if (taken.length > 0) {
+    return {
+      outcome: 'taken',
+      exit: 1,
+      results,
+      reason: `${taken.length} of ${results.length} name(s) already spoken for — rename before writing, not after the build goes red`,
+    };
+  }
+  return { outcome: 'free', exit: 0, results, reason: `all ${results.length} name(s) are free` };
+}
+
+export function renderNameCheck(decision: NameDecision, scanned?: NameFacts['scanned']): string[] {
+  const out: string[] = [];
+  if (scanned !== undefined) {
+    // Printed always, pass or fail: the operator must be able to see that the sweep looked at a real
+    // workspace and not at a directory that merely has the right shape.
+    out.push(`  swept ${scanned.packages} package(s), ${scanned.files} source file(s) — ${scanned.exports} export(s), ${scanned.commands} command(s)`);
+  }
+  for (const r of decision.results) {
+    out.push(r.verdict === 'taken'
+      ? `  [taken] ${r.kind} ${r.name} — ${r.where}`
+      : `  [free]  ${r.kind} ${r.name}`);
+  }
+  const label = decision.outcome === 'free' ? 'FREE' : decision.outcome === 'taken' ? 'TAKEN' : 'NOT ESTABLISHED';
+  out.push(`dz name-check: ${label} — ${decision.reason}`);
+  if (decision.outcome === 'free') {
+    // Said on the passing path, because that is where the limit gets forgotten: the scan reads
+    // declarations, so a re-export under a different name (`export { a as b }`) is invisible to it.
+    out.push('  note: this reads declarations in source. A re-export under a different name is not visible here — the build still owns that case.');
+  }
+  return out;
+}
+
+/**
+ * Exported identifiers declared in one TypeScript source file.
+ *
+ * Deliberately a scanner over DECLARATIONS, not a loader of the built package (ADR-001): a stale
+ * `dist` answers "free" about a name the source already took, and answers it confidently. MEASURED
+ * 2026-08-22 in this repo — half an hour of live runs against a previous build while `tsc` was red.
+ */
+/**
+ * Source with comments blanked out, quotes respected.
+ *
+ * Trivia may sit between ANY two tokens: an `export` followed by a block comment and then `class`
+ * was reported FREE, because the declaration pattern expects the keyword to be adjacent
+ * (cross-family review round 4, codex gpt-5.6-sol, 2026-08-24). Rather than widen the pattern for
+ * one shape of trivia, the trivia is removed first — which fixes the whole class at once.
+ *
+ * Newlines are PRESERVED so line-anchored patterns keep their anchors.
+ */
+export function stripComments(source: string): string {
+  let out = '';
+  let i = 0;
+  let quote: string | null = null;
+  // The previous significant character decides whether a `/` opens a REGEX or divides. Without that
+  // distinction the regex literal `/[/*]/` reads as a block-comment opener and everything after it
+  // is blanked — so a later `export const Taken = 2;` vanished and was reported FREE (cross-family
+  // review round 5, codex gpt-5.6-sol, 2026-08-24).
+  let prev = '';
+  const REGEX_MAY_FOLLOW = new Set(['', '(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';', '+', '-', '*', '%', '~', '^', '<', '>', '\n']);
+  const KEYWORD_BEFORE_REGEX = /\b(return|typeof|case|in|of|new|delete|void|instanceof|do|else|yield|await)\s*$/;
+  while (i < source.length) {
+    const c = source[i] as string;
+    const next = source[i + 1];
+    if (quote !== null) {
+      out += c;
+      if (c === '\\') { out += next ?? ''; i += 2; continue; }
+      if (c === quote) quote = null;
+      i++;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; i++; prev = c; continue; }
+    // Comment forms are checked FIRST because they are unambiguous: a regex literal can begin
+    // with neither `/` nor `*`. Putting the regex check first made a block comment at the start
+    // of a line look like a literal and survive the strip — a regression caught by its own test.
+    if (c === '/' && next === '/') {
+      while (i < source.length && source[i] !== '\n') { out += ' '; i++; }
+      prev = '\n';
+      continue;
+    }
+    if (c === '/' && next === '*') {
+      const close = source.indexOf('*/', i + 2);
+      if (close === -1) {
+        // An UNTERMINATED block comment is not a comment — it is a misread. Blanking to EOF turned
+        // every heuristic slip into a whole-file loss: `if (true) /[/*]/.test('*')` was read as an
+        // opener after `)`, and every export below it vanished and was reported FREE (cross-family
+        // review round 6, codex gpt-5.6-sol, 2026-08-24). Real source with an unclosed comment does
+        // not compile, so treating the text as text is strictly the safer reading: the worst case
+        // becomes a false TAKEN, which is conservative, instead of a false FREE, which is a lie.
+        out += c;
+        prev = c;
+        i++;
+        continue;
+      }
+      const stop = close + 2;
+      for (let k = i; k < stop; k++) out += source[k] === '\n' ? '\n' : ' ';
+      i = stop;
+      prev = ' ';
+      continue;
+    }
+    if (c === '/' && (REGEX_MAY_FOLLOW.has(prev) || KEYWORD_BEFORE_REGEX.test(out))) {
+      // A regex literal: copy it verbatim to its unescaped closing slash. A `/` inside a character
+      // class does not close it.
+      let j = i + 1;
+      let inClass = false;
+      let closed = false;
+      while (j < source.length) {
+        const d = source[j] as string;
+        if (d === '\\') { j += 2; continue; }
+        if (d === '\n') break;                       // an unterminated literal is not one
+        if (d === '[') inClass = true;
+        else if (d === ']') inClass = false;
+        else if (d === '/' && !inClass) { closed = true; j++; break; }
+        j++;
+      }
+      if (closed) { out += source.slice(i, j); prev = '/'; i = j; continue; }
+      // Not a regex after all — fall through to the comment checks below.
+    }
+    out += c;
+    if (!/\s/.test(c) || c === '\n') prev = c;
+    i++;
+  }
+  return out;
+}
+
+export function exportedNamesIn(rawSource: string): string[] {
+  const source = stripComments(rawSource);
+  const names = new Set<string>();
+  // Non-binding declarations export exactly one name. The KEYWORD SET is the correctness of this
+  // line just as much as the modifier set was: `export namespace Taken {}` was reported FREE because
+  // `namespace` was missing (cross-family review round 3, codex gpt-5.6-sol, 2026-08-24). `module` is
+  // the legacy spelling of the same thing and is admitted with it.
+  const decl = /^\s*export\s+(?:(?:declare|abstract|async)\s+)*(?:function|class|interface|type|enum|namespace|module)\s+([A-Za-z_$][\w$]*)/gm;
+  for (let m = decl.exec(source); m !== null; m = decl.exec(source)) if (m[1] !== undefined) names.add(m[1]);
+
+  // `const`/`let`/`var` can declare MANY names in one statement, and only the first was captured:
+  // `export const Seen = 1, Taken = 2;` reported `Taken` FREE (cross-family review round 2, codex
+  // gpt-5.6-sol, 2026-08-24). Destructuring exports names too. So the declarator list is parsed.
+  const binding = /^\s*export\s+(?:declare\s+)*(?:const|let|var)\s+/gm;
+  for (let m = binding.exec(source); m !== null; m = binding.exec(source)) {
+    for (const n of declaredBindingNames(source.slice(m.index + m[0].length))) names.add(n);
+  }
+
+  // `export { a, b as c }` — the EXPORTED name is what a consumer collides with, so for an alias it
+  // is the right-hand side. A bare list contributes its own names.
+  const list = /^\s*export\s*\{([^}]*)\}/gm;
+  for (let m = list.exec(source); m !== null; m = list.exec(source)) {
+    for (const raw of (m[1] ?? '').split(',')) {
+      const part = raw.trim();
+      if (part === '' || part.startsWith('*')) continue;
+      const alias = /\bas\s+([A-Za-z_$][\w$]*)\s*$/.exec(part);
+      const bare = /^(?:type\s+)?([A-Za-z_$][\w$]*)$/.exec(part);
+      const picked = alias?.[1] ?? bare?.[1];
+      if (picked !== undefined && picked !== 'default') names.add(picked);
+    }
+  }
+  return [...names];
+}
+
+const BINDING_NOISE: ReadonlySet<string> = new Set(['readonly', 'as', 'const', 'await', 'typeof']);
+
+/**
+ * Every name bound by one `const`/`let`/`var` statement, given the text just after the keyword.
+ *
+ * Walks to the statement end at depth zero, splits the declarator list on top-level commas, and for
+ * each declarator takes the identifiers before its first top-level `=` or `:` — so an initialiser
+ * and a type annotation contribute nothing, while `a, b`, `{ a, b }` and `[a, b]` all do.
+ */
+function declaredBindingNames(after: string): string[] {
+  let depth = 0;
+  let end = after.length;
+  for (let i = 0; i < after.length; i++) {
+    const c = after[i] as string;
+    if (c === '(' || c === '[' || c === '{') depth++;
+    else if (c === ')' || c === ']' || c === '}') { if (depth === 0) { end = i; break; } depth--; }
+    else if (c === ';' && depth === 0) { end = i; break; }
+  }
+  const stmt = after.slice(0, end);
+  const parts: string[] = [];
+  let level = 0;
+  let start = 0;
+  for (let i = 0; i < stmt.length; i++) {
+    const c = stmt[i] as string;
+    if (c === '(' || c === '[' || c === '{') level++;
+    else if (c === ')' || c === ']' || c === '}') level--;
+    else if (c === ',' && level === 0) { parts.push(stmt.slice(start, i)); start = i + 1; }
+  }
+  parts.push(stmt.slice(start));
+
+  const out: string[] = [];
+  for (const part of parts) {
+    let head = part;
+    let lvl = 0;
+    for (let i = 0; i < part.length; i++) {
+      const c = part[i] as string;
+      if (c === '(' || c === '[' || c === '{') lvl++;
+      else if (c === ')' || c === ']' || c === '}') lvl--;
+      else if ((c === '=' || c === ':') && lvl === 0) { head = part.slice(0, i); break; }
+    }
+    for (const m of head.matchAll(/[A-Za-z_$][\w$]*/g)) {
+      if (!BINDING_NOISE.has(m[0])) out.push(m[0]);
+    }
+  }
+  return out;
+}
+
+/** Command names a CLI source dispatches. The help block is scanned separately by the caller. */
+export function dispatchedCommandsIn(source: string): string[] {
+  const names = new Set<string>();
+  const re = /^\s*case\s+'([a-z][a-z0-9-]*)':/gm;
+  for (let m = re.exec(source); m !== null; m = re.exec(source)) if (m[1] !== undefined) names.add(m[1]);
+  return [...names];
+}

package/src/operations.ts

@@ -1070,18 +1070,39 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
   // Silent when a log is absent or has never been chained: an unchained file is legal (FR-5), not a
   // fault, and reporting it would train the reader to ignore this line.
   try {
-    const { verifyEventChainText, EVENT_CHAIN_SCOPE } = await import('./event-chain.js');
+    const { verifyEventChainText, classifyChainDefects, EVENT_CHAIN_SCOPE } = await import('./event-chain.js');
     for (const rel of ['recall-usage.jsonl', 'guard-audit.jsonl']) {
       const p = join(root, '.dz', rel);
       if (!existsSync(p)) continue;
-      const v = verifyEventChainText(readFileSync(p, 'utf-8'));
+      const text = readFileSync(p, 'utf-8');
+      const v = verifyEventChainText(text);
       if (v.chained === 0 || v.ok) continue;
+      const total = text.split('\n').filter((l) => l.trim() !== '').length;
+      const age = classifyChainDefects(v, total);
+      const named = `${v.defects.length} defect(s): ${v.defects.slice(0, 3).map((d) => `${d.kind}@L${d.line}`).join(', ')}`;
+      // A break that an unbroken run has already outlived is not a reason to distrust today's
+      // records. Reporting both alike made this line PERMANENTLY red for four weeks — MEASURED
+      // 2026-08-24: every defect in both logs is historical, with 998 of 1138 rows in one and 88 of
+      // 426 in the other forming an unbroken run after the last of them. The verdict was true of the
+      // file and false of the present, and a red nobody can act on is a red nobody reads.
+      if (age.inRun.length === 0 && age.runRecords > 0) {
+        checks.push({
+          name: `evidence chain (.dz/${rel})`,
+          ok: true,
+          // The COUNT carries the meaning, and is printed first for that reason: "1 record forms an
+          // unbroken run" is true and says almost nothing, while 998 says a great deal. Naming the
+          // position without the count would overclaim on the reader's behalf (cross-family review,
+          // codex gpt-5.6-sol, 2026-08-24).
+          detail:
+            `${named} — all BEFORE the current run: the last ${age.runRecords} record(s), from L${age.runFrom}, are unbroken, ` +
+            `so verdicts over those ${age.runRecords} are sound. The break itself cannot be un-happened. Scope: ${EVENT_CHAIN_SCOPE}`,
+        });
+        continue;
+      }
       checks.push({
         name: `evidence chain (.dz/${rel})`,
         ok: false,
-        detail:
-          `${v.defects.length} defect(s): ${v.defects.slice(0, 3).map((d) => `${d.kind}@L${d.line}`).join(', ')}` +
-          ` — learning verdicts computed from this log are unsafe. Scope: ${EVENT_CHAIN_SCOPE}`,
+        detail: `${named} — with NO sound records after them: learning verdicts computed from this log are unsafe. Scope: ${EVENT_CHAIN_SCOPE}`,
       });
     }
   } catch {

package/src/provenance.ts

@@ -0,0 +1,217 @@
+/**
+ * The provenance gate — nothing leaves this machine citing a source that may not.
+ *
+ * It checks PROVENANCE, not words. A denylist of forbidden phrases is an enumeration, and it loses
+ * to the first confidential note it has never heard of; the `.gitignore` in this repository carries
+ * a comment warning about exactly that mistake. An allowlist of SOURCES wins by construction: an
+ * unknown source is refused because it is unknown.
+ *
+ * Two things this module deliberately does NOT do, both named in ADR-001 rather than implied:
+ *  - it does not read CONTENT, so confidential text pasted by hand into an allowed file inherits
+ *    that file's permission;
+ *  - it cannot see a paraphrase with no citation. It proves what was CITED, never what was known.
+ * The last line against both is a person reading the draft, and that is the design, not a gap.
+ *
+ * PURE: no filesystem, no git, no clock. The oracle runs in the CLI and arrives as a fact — a
+ * verdict that needs a real repository to reproduce is a verdict no test can pin.
+ *
+ * See features/provenance-gate/03_adr/ for the decisions and the measurements behind them.
+ */
+
+/** Why one claim was refused. A CLOSED set, so a reason is machine-readable and never prose. */
+export type SourceVerdict =
+  | 'allowed'
+  /** The claim names no source at all. A claim with no source is the thing we must not publish. */
+  | 'no-source'
+  /** The manifest did not declare what kind of source this is — never inferred from its shape. */
+  | 'unknown-kind'
+  /** A store record that the TRACKED public list does not name. Default-deny. */
+  | 'not-marked-public'
+  /** The path does not resolve. You cannot cite what does not exist. */
+  | 'unresolvable'
+  /** Resolved outside the repository — a symlink out of the tree lands here too. */
+  | 'outside-repo'
+  /** Git says this path is ignored: the owner's own boundary refuses it. */
+  | 'ignored-path'
+  /** Not tracked by git — nobody has reviewed it, so "not ignored" proves nothing about it. */
+  | 'untracked'
+  /** Tracked, but carrying uncommitted changes: its CURRENT contents went through no review. */
+  | 'uncommitted';
+
+export type SourceProvenanceOutcome = 'allowed' | 'blocked' | 'not-established';
+
+/** One claim in a draft, and where it came from. */
+export interface SourceClaim {
+  readonly id: string;
+  /** `path` — a file in the repository. `record` — an addressed row in a `.dz` store. */
+  readonly kind?: string;
+  readonly source?: string;
+}
+
+export interface SourceManifest {
+  readonly version: number;
+  readonly draft: string;
+  readonly claims: readonly SourceClaim[];
+}
+
+export interface SourceProvenanceFacts {
+  /**
+   * Paths git reported as ignored. `null` means THE ORACLE DID NOT RUN — a different fact from
+   * "nothing is ignored", and the one a naive gate reads as "everything is allowed". Measured in
+   * this repo on a sibling command: `dz sync` prints `0/0` and exits 0 when it compared nothing.
+   */
+  readonly ignoredPaths: ReadonlySet<string> | null;
+  /**
+   * Record addresses declared public in a GIT-TRACKED file. Not a `visibility` field inside the
+   * record: `.dz/` is gitignored, so a marker there appears in no diff, and the process that writes
+   * the draft can write it too. MEASURED 2026-08-22: `grep -r '"visibility"' .dz/` returns 0 — the
+   * field does not exist, and introducing it would have made "the owner opted in" mean "the
+   * generator marked itself" (ADR-001).
+   */
+  readonly publicRecords: ReadonlySet<string>;
+  /** Each `path` source resolved through the filesystem; `null` = missing or outside the repo. */
+  readonly resolved: ReadonlyMap<string, string | null>;
+  /**
+   * Resolved paths git tracks. "Not ignored" is NOT "reviewed": a file the drafting process wrote a
+   * second ago is neither, and the first version cleared it while calling it "a tracked path"
+   * (cross-family review round 3, codex `gpt-5.6-sol`, 2026-08-22).
+   */
+  readonly trackedPaths: ReadonlySet<string>;
+  /** Tracked paths with uncommitted changes — committed is what "reviewed" means here. */
+  readonly dirtyPaths: ReadonlySet<string>;
+}
+
+export interface SourceClaimResolution {
+  readonly id: string;
+  readonly source: string | null;
+  readonly verdict: SourceVerdict;
+  readonly detail: string;
+}
+
+export interface SourceProvenanceDecision {
+  readonly outcome: SourceProvenanceOutcome;
+  /** 0 allowed · 1 blocked · 3 not established. A zero is only ever a proven pass. */
+  readonly exit: 0 | 1 | 3;
+  readonly claims: readonly SourceClaimResolution[];
+  readonly reason: string;
+}
+
+/** Parse a manifest. Unparseable is `null` — which the caller must NOT read as "empty". */
+export function parseSourceManifest(text: string): SourceManifest | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (raw === null || typeof raw !== 'object') return null;
+  const o = raw as Record<string, unknown>;
+  if (!Array.isArray(o['claims'])) return null;
+  const claims: SourceClaim[] = [];
+  for (const c of o['claims'] as unknown[]) {
+    if (c === null || typeof c !== 'object') return null;
+    const cc = c as Record<string, unknown>;
+    claims.push({
+      id: typeof cc['id'] === 'string' ? cc['id'] : '',
+      ...(typeof cc['kind'] === 'string' ? { kind: cc['kind'] } : {}),
+      ...(typeof cc['source'] === 'string' ? { source: cc['source'] } : {}),
+    });
+  }
+  return {
+    version: typeof o['version'] === 'number' ? o['version'] : 1,
+    draft: typeof o['draft'] === 'string' ? o['draft'] : '',
+    claims,
+  };
+}
+
+/**
+ * Classify ONE claim's source.
+ *
+ * Order matters and is load-bearing. The KIND is read from the manifest and never guessed from the
+ * string: `.dz/` holds 119 git-TRACKED files (measured), so `.dz/guard-audit.jsonl` is not ignored
+ * and a shape-based guess would let it through as an ordinary repo path, skipping the public-list
+ * requirement entirely.
+ */
+export function classifySource(claim: SourceClaim, facts: SourceProvenanceFacts): SourceClaimResolution {
+  const id = claim.id === '' ? '(unnamed claim)' : claim.id;
+  const source = typeof claim.source === 'string' && claim.source.trim() !== '' ? claim.source.trim() : null;
+  const at = (verdict: SourceVerdict, detail: string): SourceClaimResolution => ({ id, source, verdict, detail });
+
+  if (source === null) return at('no-source', 'the claim names no source — a claim with no source is exactly what must not go out');
+
+  if (claim.kind === 'record') {
+    return facts.publicRecords.has(source)
+      ? at('allowed', 'named in the tracked public-records list')
+      : at('not-marked-public', 'this record is not in the tracked public list — marking one public must be a reviewable commit, not a field inside an ignored store');
+  }
+
+  if (claim.kind === 'path') {
+    const real = facts.resolved.get(source);
+    if (real === undefined || real === null) {
+      return at('unresolvable', 'the path does not resolve inside the repository — a source that cannot be resolved cannot be shown to be safe');
+    }
+    if (facts.ignoredPaths === null) {
+      // Defensive: `decideSourceProvenance` refuses before reaching here. Kept so a direct caller of
+      // classifySource cannot obtain an `allowed` from an oracle that never ran.
+      return at('unresolvable', 'the ignore oracle did not run, so no path can be cleared');
+    }
+    if (facts.ignoredPaths.has(real)) return at('ignored-path', 'git says this path is ignored — the owner\'s own boundary refuses it');
+    // Three separate questions, and the first version asked only one. A brand-new file the drafting
+    // process wrote is not ignored either, and clearing it would let the generator author its own
+    // evidence.
+    if (!facts.trackedPaths.has(real)) return at('untracked', 'git does not track this path, so nobody has reviewed it — not being ignored says nothing about a file that has never been committed');
+    if (facts.dirtyPaths.has(real)) return at('uncommitted', 'this path has uncommitted changes, so its current contents went through no review');
+    return at('allowed', 'committed, reviewed, and not refused by the owner\'s boundary');
+  }
+
+  return at('unknown-kind', `the manifest declares kind ${JSON.stringify(claim.kind ?? null)} — a kind this gate cannot check is refused, never inferred from the path's shape`);
+}
+
+/**
+ * The whole-manifest verdict.
+ *
+ * Three outcomes, and neither non-pass returns zero. The dangerous one is the third: an empty
+ * manifest does not mean "nothing confidential is cited", it means "we checked nothing".
+ */
+export function decideSourceProvenance(manifest: SourceManifest | null, facts: SourceProvenanceFacts): SourceProvenanceDecision {
+  if (manifest === null) {
+    return { outcome: 'not-established', exit: 3, claims: [], reason: 'the manifest could not be read — nothing was checked, which is not the same as nothing being wrong' };
+  }
+  if (facts.ignoredPaths === null) {
+    // BEFORE classification, and for the WHOLE batch. Measured 2026-08-22: one out-of-repo path in
+    // a `git check-ignore --stdin` batch prints the matches found so far, then dies with exit 128 —
+    // so crediting what was printed would clear every path queued behind it (ADR-003).
+    return { outcome: 'not-established', exit: 3, claims: [], reason: 'the ignore oracle did not run, so not one path was checked — this is not a pass' };
+  }
+  if (manifest.claims.length === 0) {
+    return { outcome: 'not-established', exit: 3, claims: [], reason: 'the manifest lists no claims — a draft with nothing to check has not been shown to be safe, only left unchecked' };
+  }
+  const claims = manifest.claims.map((c) => classifySource(c, facts));
+  const blocked = claims.filter((c) => c.verdict !== 'allowed');
+  if (blocked.length > 0) {
+    return {
+      outcome: 'blocked',
+      exit: 1,
+      claims,
+      reason: `${blocked.length} of ${claims.length} claim(s) cite a source that may not leave this machine`,
+    };
+  }
+  return { outcome: 'allowed', exit: 0, claims, reason: `all ${claims.length} claim(s) cite a source cleared to go out` };
+}
+
+/** What the operator sees. Every blocked claim names its id, its source and its reason. */
+export function renderSourceProvenance(decision: SourceProvenanceDecision): string[] {
+  const out: string[] = [];
+  const label = decision.outcome === 'allowed' ? 'ALLOWED' : decision.outcome === 'blocked' ? 'BLOCKED' : 'NOT ESTABLISHED';
+  for (const c of decision.claims) {
+    if (c.verdict === 'allowed') continue;
+    out.push(`  [${c.verdict}] ${c.id} — ${c.source ?? '(no source)'}: ${c.detail}`);
+  }
+  out.push(`dz provenance-check: ${label} — ${decision.reason}`);
+  if (decision.outcome === 'allowed') {
+    // Said on the PASSING path too, because that is the path where it gets forgotten: a green tick
+    // here proves where the citations came from, not that the prose is safe.
+    out.push('  note: this proves what was CITED. It cannot see a paraphrase with no citation, nor confidential text pasted by hand into an allowed file. Read the draft.');
+  }
+  return out;
+}

package/src/recall-domain-boost.ts

@@ -64,8 +64,8 @@ export function domainMatch(hitDomain: string | null | undefined, wanted: string
   return 'none';
 }
 
-export interface DomainBoostResult {
-  readonly hits: readonly RecallHit[];
+export interface DomainBoostResult<T extends RecallHit = RecallHit> {
+  readonly hits: readonly T[];
   /** How many hits MATCHED the domain (exactly / relatedly). */
   readonly exact: number;
   readonly related: number;
@@ -88,7 +88,14 @@ export interface DomainBoostResult {
  * is deterministic — the same input always yields the same output, which is what
  * makes it testable at all.
  */
-export function applyDomainBoost(hits: readonly RecallHit[], wanted: string | null | undefined): DomainBoostResult {
+/**
+ * Generic over the hit type so EXTRA FIELDS SURVIVE the boost. Narrowing to `RecallHit` silently
+ * dropped `similarity` from a `HybridHit`, and the closeness a reader is meant to act on vanished
+ * the moment `--domain` was passed. Note the deliberate asymmetry with `relevance`, which the CLI
+ * nulls under a boost because the boost invalidates the RRF ordering: closeness is
+ * ORDER-INDEPENDENT, so it stays populated.
+ */
+export function applyDomainBoost<T extends RecallHit>(hits: readonly T[], wanted: string | null | undefined): DomainBoostResult<T> {
   const target = normalizeDomain(wanted);
   if (target === '' || hits.length === 0) {
     return { hits, exact: 0, related: 0, moved: 0, noMatches: true };