@ecoma-io/archkeep 0.14.0 → 0.15.0

package/src/commands/delta-snapshot.mjs

@@ -19,6 +19,23 @@
  * this file is read back by `parseEvidenceSnapshot` alone, never by the report
  * renderers, and the two formats will evolve on different clocks.
  *
+ * ## The two OPTIONAL blocks, and why the version stays 1
+ *
+ * `customRules` (the declared rows: name, artifact, sha256, params) and
+ * `owned` (the workspace's file→project ownership map) are stored only when
+ * the capturing policy declares `customRules` — a workspace that declares
+ * none produces byte-identical snapshots before and after this addition, and
+ * a reader of version 1 that predates the blocks ignores keys it never asks
+ * for. Both are evidence in the same sense the records are: the rows are what
+ * lets a compare run say whether the custom LAW moved between capture and
+ * head (digest or params drift), and `owned` is what lets the base-side
+ * evidence bundle attribute each stored record — ownership is the workspace
+ * layer's answer (`../workspace.mjs`) and cannot be re-derived from a graph
+ * that may have changed since. A baseline WITHOUT the blocks is still legal
+ * (an old capture, or one whose policy declared no rules); downstream every
+ * custom finding then classifies `unknown` with a re-capture reason rather
+ * than the blocks' absence reading as "no custom rules existed at base".
+ *
  * ## Purity seam
  *
  * Everything decidable is pure: `buildEvidenceSnapshot` takes already-resolved
@@ -72,6 +89,14 @@ export const EVIDENCE_SNAPSHOT_SCHEMA_VERSION = 1;
  * @param {object[]} input.records The raw import-site records — the analysis
  *   envelope's `imports` array verbatim (`../analysis/contract.md`), including
  *   the `resolved: null` rows.
+ * @param {{name: string, artifact: string, sha256: string,
+ *   params?: Record<string, any>}[]} [input.customRules] The declared
+ *   custom-rule rows, when the capturing policy declares any — see the header's
+ *   optional-blocks section. Omitted means "the capturing policy declared no
+ *   custom rules", and the snapshot carries no key at all.
+ * @param {{file: string, project: string}[]} [input.owned] The ownership map,
+ *   required exactly when `customRules` is given: the base-side evidence
+ *   bundle cannot attribute a record without it. Stored sorted by file.
  * @returns {object} The snapshot, ready for `serializeEvidenceSnapshot`.
  * @throws {Error} naming the first piece of required structure that is missing
  *   or malformed — a snapshot built over half-specified evidence would fail
@@ -85,6 +110,8 @@ export function buildEvidenceSnapshot({
   coverage,
   graph,
   records,
+  customRules,
+  owned,
 }) {
   if (!tool || typeof tool.name !== "string" || tool.name === "") {
     throw new Error(
@@ -147,6 +174,22 @@ export function buildEvidenceSnapshot({
     }
   }
 
+  if (customRules !== undefined) {
+    const customProblems = describeCustomRuleBlockProblems(customRules, owned);
+    if (customProblems.length > 0) {
+      throw new Error(
+        "archkeep: cannot build an evidence snapshot — the custom-rule evidence is malformed:\n  " +
+          customProblems.join("\n  "),
+      );
+    }
+  } else if (owned !== undefined) {
+    throw new Error(
+      "archkeep: cannot build an evidence snapshot with an `owned` map but no `customRules` " +
+        "rows — the map exists to attribute the base side of a custom-rule re-judgment, and " +
+        "storing it alone would claim custom-rule evidence the snapshot does not hold",
+    );
+  }
+
   const projects = buildProjects(graph.nodes).map((project) => {
     // Re-attach the three rule-relevant fields `buildProjects` strips for the
     // public graph contract. Each is attached only when the node DECLARES it —
@@ -179,7 +222,8 @@ export function buildEvidenceSnapshot({
     storedGraph.exemptedFiles = graph.exemptedFiles.slice().sort(cmpString);
   }
 
-  return {
+  /** @type {Record<string, unknown>} */
+  const snapshot = {
     schemaVersion: EVIDENCE_SNAPSHOT_SCHEMA_VERSION,
     tool: { name: tool.name, version: tool.version },
     provider,
@@ -194,6 +238,25 @@ export function buildEvidenceSnapshot({
     graph: storedGraph,
     records,
   };
+  if (customRules !== undefined) {
+    // The declared rows, each reduced to the four fields a compare run reads:
+    // identity (name), the pinned law (artifact + sha256), and the parameters
+    // that ride inside the evidence bundle — params drift is law drift, the
+    // same as digest drift. `reason` and the governance block stay out: they
+    // explain the row to a human and change no judgment.
+    snapshot.customRules = customRules.map((row) => ({
+      name: row.name,
+      artifact: row.artifact,
+      sha256: row.sha256,
+      ...(row.params === undefined ? {} : { params: row.params }),
+    }));
+    // Sorted by file for byte-determinism; `createWorkspace` derives the map
+    // from a Set walk whose order is an accident of the file listing.
+    snapshot.owned = /** @type {{file: string, project: string}[]} */ (owned)
+      .map(({ file, project }) => ({ file, project }))
+      .sort((a, b) => cmpString(a.file, b.file));
+  }
+  return snapshot;
 }
 
 /**
@@ -400,6 +463,18 @@ export function parseEvidenceSnapshot(text, path) {
     });
   }
 
+  // The optional custom-rule pair: absence is a legal old-or-undeclared
+  // baseline, presence must be sound — a half-readable block consumed
+  // silently would attribute base records against a map that is not one.
+  if (parsed.customRules !== undefined) {
+    problems.push(...describeCustomRuleBlockProblems(parsed.customRules, parsed.owned));
+  } else if (parsed.owned !== undefined) {
+    problems.push(
+      "owned: present without customRules — the map only exists as custom-rule evidence, and " +
+        "half the pair is a snapshot no release ever wrote",
+    );
+  }
+
   if (problems.length > 0) {
     throw new Error(
       `archkeep: the evidence snapshot '${path}' is not a usable baseline:\n  ` +
@@ -487,6 +562,86 @@ function describeCoverageProblems(coverage) {
   return problems;
 }
 
+/**
+ * Everything wrong with the optional custom-rule evidence pair, as messages —
+ * shared by capture-time construction and load-time parsing for the same
+ * reason `describeCoverageProblems` is: one statement of what the blocks are.
+ *
+ * Called only when `customRules` is PRESENT: absence is legal (an old
+ * baseline, or a policy that declares none) and is judged by the caller. When
+ * the rows are present the `owned` map must be too — a base-side re-judgment
+ * without attribution would hand every rule evidence it must refuse, and the
+ * time to say so is when the snapshot is built or read, not per rule at
+ * compare time.
+ *
+ * @param {unknown} customRules The stored (or to-be-stored) rule rows.
+ * @param {unknown} owned The stored (or to-be-stored) ownership map.
+ * @returns {string[]} One entry per problem, empty when both are sound.
+ */
+function describeCustomRuleBlockProblems(customRules, owned) {
+  const problems = [];
+  if (!Array.isArray(customRules)) {
+    problems.push(
+      `customRules: must be an array of declared rule rows when present, got ` +
+        `${describe(customRules)}`,
+    );
+  } else {
+    /** @type {Map<string, number>} */
+    const firstIndexOfName = new Map();
+    customRules.forEach((row, index) => {
+      if (!isPlainObject(row)) {
+        problems.push(`customRules[${index}]: must be an object, got ${describe(row)}`);
+        return;
+      }
+      for (const field of ["name", "artifact", "sha256"]) {
+        if (typeof row[field] !== "string" || row[field] === "") {
+          problems.push(`customRules[${index}].${field}: must be a non-empty string`);
+        }
+      }
+      // A duplicate name is a loud refusal, not a last-one-wins: the compare
+      // side keys stored rows by name (`./custom-rules.mjs`'s
+      // `customRulesForDelta` builds a Map over them), so a second row under
+      // one name would silently shadow the first — and which law the delta
+      // then matched against would be an accident of row order.
+      if (typeof row.name === "string" && row.name !== "") {
+        const first = firstIndexOfName.get(row.name);
+        if (first !== undefined) {
+          problems.push(
+            `customRules[${index}].name: duplicates customRules[${first}].name ("${row.name}") — ` +
+              `rule names are the identity a delta matches base rows by, and two rows under one ` +
+              `name would silently shadow each other`,
+          );
+        } else {
+          firstIndexOfName.set(row.name, index);
+        }
+      }
+      if (row.params !== undefined && !isPlainObject(row.params)) {
+        problems.push(`customRules[${index}].params: must be a plain object when present`);
+      }
+    });
+  }
+  if (!Array.isArray(owned)) {
+    problems.push(
+      `owned: must be an array of {file, project} rows whenever customRules is stored — the ` +
+        `base side of a custom-rule re-judgment cannot attribute a record without it, got ` +
+        `${describe(owned)}`,
+    );
+  } else {
+    owned.forEach((row, index) => {
+      if (!isPlainObject(row)) {
+        problems.push(`owned[${index}]: must be an object, got ${describe(row)}`);
+        return;
+      }
+      for (const field of ["file", "project"]) {
+        if (typeof row[field] !== "string" || row[field] === "") {
+          problems.push(`owned[${index}].${field}: must be a non-empty string`);
+        }
+      }
+    });
+  }
+  return problems;
+}
+
 /**
  * The reason a coverage summary cannot serve as a delta BASELINE, or `null`.
  *

package/src/commands/delta.mjs

@@ -19,8 +19,9 @@
  * Unlike `diff` — which compares two GRAPH snapshots edge by edge and never
  * exits 1 — `delta` is a gate: a non-waived introduced violation is a finding
  * (exit 1), which is the whole point of carrying re-judgeable evidence rather
- * than a graph. That makes `delta` the third verb whose verdict carries
- * exit 1, beside `check` and `fitness`.
+ * than a graph. That made `delta` the third verb whose verdict carries
+ * exit 1, beside `check` and `fitness`; `./change.mjs` later became the
+ * fourth, over a different question — declared intent versus observed delta.
  *
  * Refusals (each a throw, exit 3 upstream — a delta that could not honestly
  * classify must never read as "no change"):
@@ -48,12 +49,15 @@
 import { createRequire } from "node:module";
 
 import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { stripTrailingSlashes } from "../path-util.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { buildDecision } from "../report/evidence.mjs";
 import { formatDeltaReport } from "../report/delta-text.mjs";
+import { formatDeltaSarif } from "../report/sarif.mjs";
 import { evaluateRun } from "../rules/index.mjs";
-import { classifyDelta } from "./delta-classify.mjs";
+import { customRulesForDelta, declaresCustomRules } from "./custom-rules.mjs";
+import { classifyCustomFindings, classifyDelta } from "./delta-classify.mjs";
 import {
   buildEvidenceSnapshot,
   providerMismatch,
@@ -72,11 +76,17 @@ const { name: TOOL_NAME, version: TOOL_VERSION } = require("../../package.json")
  * Refuses the two head states no delta side may be built over, shared by both
  * modes: the unregistered-plugin graph and incomplete analysis coverage.
  *
+ * Exported since `change` arrived because that command builds its comparison
+ * over the same two head states — a graph that under-represents the tree and
+ * an analysis with holes would reconcile a declaration against architecture
+ * nobody observed — and a second copy of the refusal is where the two
+ * commands would drift into answering "may this head be judged?" differently.
+ *
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {string} activity Which mode is refusing, for the message.
  * @throws {Error} on either condition.
  */
-function refuseUnjudgeableHead(commandContext, activity) {
+export function refuseUnjudgeableHead(commandContext, activity) {
   const { provider, pluginGap } = commandContext;
   if (provider === "nx" && !pluginGap.registered && pluginGap.manifests.length > 0) {
     throw new Error(
@@ -123,6 +133,12 @@ export function captureDelta(commandContext, { config }) {
   }
   const { root, provider, graph, analysis } = commandContext;
   const snapshot = buildEvidenceSnapshot({
+    // The two optional custom-rule blocks, stored exactly when the capturing
+    // policy declares rules — an undeclaring workspace's snapshot stays
+    // byte-identical (`./delta-snapshot.mjs`, the optional-blocks section).
+    ...(declaresCustomRules(config)
+      ? { customRules: config.customRules, owned: commandContext.owned }
+      : {}),
     tool: { name: TOOL_NAME, version: TOOL_VERSION },
     provenance: resolveProvenance(root),
     provider,
@@ -223,11 +239,16 @@ export function evidenceGraphToProjectGraph(storedGraph) {
  * head does not already claim — so a base-side record living in a directory
  * the head no longer has still attributes to the project that owned it.
  *
+ * Exported for `./change.mjs`, which classifies the same two evidence sets
+ * through `./delta-classify.mjs` and must attribute unresolvable records the
+ * same way a delta does — a second attribution rule beside this one is how
+ * the two commands would disagree about which project carried a site.
+ *
  * @param {object} headGraph The current run's graph (`nodes` map).
  * @param {object[]} baselineProjects The snapshot's stored project rows.
  * @returns {(record: object) => string|null}
  */
-function sourceProjectAttributor(headGraph, baselineProjects) {
+export function sourceProjectAttributor(headGraph, baselineProjects) {
   /** @type {Map<string, string>} root → project name, head winning ties. */
   const byRoot = new Map();
   for (const node of Object.values(headGraph.nodes ?? {})) {
@@ -240,7 +261,7 @@ function sourceProjectAttributor(headGraph, baselineProjects) {
     }
   }
   const entries = [...byRoot.entries()]
-    .map(([root, name]) => [root.replace(/\/+$/u, ""), name])
+    .map(([root, name]) => [stripTrailingSlashes(root), name])
     .sort((a, b) => b[0].length - a[0].length);
   return (record) => {
     const file = record?.sourceFile;
@@ -273,20 +294,36 @@ const short = (fingerprint) =>
  *   a tracked acceptance, not a fix — but do not fail the gate, which is what
  *   a waiver is for.
  *
+ * Custom-rule (wasm) findings join the classification when either side
+ * declares them: `./custom-rules.mjs`'s `customRulesForDelta` judges every
+ * head-declared rule over both evidence sets, `./delta-classify.mjs`'s
+ * `classifyCustomFindings` buckets the findings, and the result rides the
+ * envelope as `result.customRules` — a block that is ABSENT (never `null`)
+ * when neither side declares any, so an undeclaring workspace's envelope
+ * stays byte-identical. An introduced custom finding gates exactly as an
+ * introduced violation does, with no waiver lane by construction
+ * (suppressions key on a `messageId` custom findings do not have); an
+ * unclassifiable one is a no-verdict. This is also why the function is async:
+ * the wasm host is.
+ *
  * @param {string} baselinePath Absolute path to the evidence snapshot.
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {{config: object|null, readBaseline?: (path: string) => object,
- *   now?: string}} io The resolved boundary config (required — both sides
- *   are re-judged under it), an injectable baseline reader, and the one
- *   shared reference instant (defaults to the shared governance clock).
- * @returns {{status: "ok"|"findings"|"no-verdict", delta: object,
- *   coverage: object, report: {text: string, json: string}}}
- * @throws {Error} on every refusal the module header lists.
+ *   now?: string, readArtifact?: (artifact: string) => Uint8Array|null,
+ *   timeoutMs?: number}} io The resolved boundary config (required
+ *   — both sides are re-judged under it), an injectable baseline reader, the
+ *   one shared reference instant (defaults to the shared governance clock),
+ *   and the custom-rule host's two injectable seams, passed through to
+ *   `customRulesForDelta`.
+ * @returns {Promise<{status: "ok"|"findings"|"no-verdict", delta: object,
+ *   coverage: object, report: {text: string, json: string, sarif: string}}>}
+ * @throws {Error} on every refusal the module header lists, and on a
+ *   custom-rule LOAD failure (`./custom-rules.mjs` argues the split).
  */
-export function deltaCommand(
+export async function deltaCommand(
   baselinePath,
   commandContext,
-  { config, readBaseline = readEvidenceSnapshot, now = referenceTime() },
+  { config, readBaseline = readEvidenceSnapshot, now = referenceTime(), ...customRuleIo },
 ) {
   const { root, provider, marker, graph, analysis } = commandContext;
 
@@ -378,23 +415,93 @@ export function deltaCommand(
     );
   }
 
+  // The custom-rule half, present exactly when a side declares rules: judged
+  // two-sided where the law is identical, `unknown` with a mandatory reason
+  // everywhere else (`./custom-rules.mjs`'s `customRulesForDelta` owns the
+  // routes). `null` when NEITHER side declares any — the envelope block and
+  // the summary key are then absent, and an undeclaring workspace's envelope
+  // stays byte-identical (`../../../../AGENTS.md`, "a change to what is
+  // reported on an unchanged workspace is a breaking change").
+  /** @type {{judged: object[], skipped: object[], removed: string[],
+   *   findings: {introduced: object[], resolved: object[], unchanged: object[],
+   *   unknown: object[]}}|null} */
+  let custom = null;
+  // The head-declared finding catalogue, held for the SARIF face alone: the
+  // envelope deliberately does not carry it (the JSON contract predates the
+  // SARIF face and must stay byte-identical), while `sarifRules` needs it so
+  // an introduced custom finding's `ruleId` resolves to a descriptor.
+  /** @type {{ruleId: string, rule: string, findingId: string, message: string}[]} */
+  let customCatalogue = [];
+  if (declaresCustomRules(config)) {
+    const twoSided = await customRulesForDelta(commandContext, {
+      rows: config.customRules,
+      policy: config,
+      baseline,
+      ...customRuleIo,
+    });
+    customCatalogue = twoSided.catalogue;
+    custom = {
+      judged: twoSided.judged.map(({ name, sha256, notes: ruleNotes }) => ({
+        name,
+        sha256,
+        ...(ruleNotes === undefined ? {} : { notes: ruleNotes }),
+      })),
+      skipped: twoSided.unknownRules,
+      removed: twoSided.removedRules,
+      findings: classifyCustomFindings({
+        judged: twoSided.judged,
+        unknownRules: twoSided.unknownRules,
+      }),
+    };
+  } else if (baseline.customRules !== undefined) {
+    // The head declares nothing, so there is no law to judge either side
+    // under — every baseline rule is a removal, disclosed rather than judged.
+    custom = {
+      judged: [],
+      skipped: [],
+      removed: baseline.customRules.map((row) => row.name),
+      findings: { introduced: [], resolved: [], unchanged: [], unknown: [] },
+    };
+  }
+  if (custom !== null) {
+    for (const skipped of custom.skipped) {
+      notes.push(`custom rule "${skipped.name}" was not classified — ${skipped.reason}`);
+    }
+    for (const name of custom.removed) {
+      notes.push(
+        `custom rule "${name}" is declared in the baseline but not by the current policy — ` +
+          `nothing was judged for it, so its base-side findings are not classified as resolved`,
+      );
+    }
+    for (const rule of custom.judged) {
+      for (const note of rule.notes ?? []) {
+        notes.push(`custom rule "${rule.name}": ${note}`);
+      }
+    }
+  }
+
   const { violations, unresolvable } = classification;
   const introducedWaived = violations.introduced.filter((entry) => entry.waived === true).length;
   const introducedNotWaived = violations.introduced.length - introducedWaived;
-  const unknownCount = violations.unknown.length + unresolvable.unknown.length;
+  // Custom findings have no waiver lane (`./delta-classify.mjs`'s
+  // `classifyCustomFindings` argues the by-construction absence), so every
+  // introduced one gates.
+  const customIntroduced = custom === null ? 0 : custom.findings.introduced.length;
+  const customUnknown = custom === null ? 0 : custom.findings.unknown.length;
+  const unknownCount = violations.unknown.length + unresolvable.unknown.length + customUnknown;
 
   /** @type {"ok"|"findings"|"no-verdict"} */
   let status;
   /** @type {0|1|3} */
   let exitCode;
   let decision;
-  if (introducedNotWaived > 0) {
+  if (introducedNotWaived + customIntroduced > 0) {
     status = "findings";
     exitCode = 1;
     decision = buildDecision({
       status,
       coverageComplete: true,
-      findings: introducedNotWaived,
+      findings: introducedNotWaived + customIntroduced,
     });
   } else if (unknownCount > 0) {
     status = "no-verdict";
@@ -405,6 +512,9 @@ export function deltaCommand(
       findings: 0,
       reason:
         `${unknownCount} delta item${unknownCount === 1 ? "" : "s"} could not be classified — ` +
+        (customUnknown > 0
+          ? `${customUnknown} of them custom-rule item${customUnknown === 1 ? "" : "s"} — `
+          : "") +
         `an item whose identity cannot be stated is never guessed into a bucket`,
     });
   } else {
@@ -454,9 +564,20 @@ export function deltaCommand(
         unchanged: unresolvable.unchanged.length,
         unknown: unresolvable.unknown.length,
       },
+      ...(custom === null
+        ? {}
+        : {
+            customFindings: {
+              introduced: custom.findings.introduced.length,
+              resolved: custom.findings.resolved.length,
+              unchanged: custom.findings.unchanged.length,
+              unknown: custom.findings.unknown.length,
+            },
+          }),
     },
     violations,
     unresolvable,
+    ...(custom === null ? {} : { customRules: custom }),
   };
 
   const envelope = jsonEnvelope({
@@ -476,6 +597,10 @@ export function deltaCommand(
     report: {
       text: formatDeltaReport({ delta: result, coverage }),
       json: renderJson(envelope),
+      // Eager beside the other two faces: the render is pure and cheap, and a
+      // lazy face is one a caller can forget to build — the SARIF is the same
+      // verdict, ready whichever face `--format` selects.
+      sarif: formatDeltaSarif({ delta: result, coverage, customCatalogue }),
     },
   };
 }

package/src/commands/diff.mjs

@@ -216,13 +216,29 @@ function buildHeadSnapshot(commandContext) {
   };
 }
 
+/**
+ * The identity key of one dependency record: the `(source, target, type)`
+ * triple joined with `\0`. Extracted from `computeDiff`'s index maps so a
+ * second consumer (`./trajectory.mjs`'s persistence sets) keys edges the SAME
+ * way the diff does — a second spelling of this string would be a second
+ * definition of "same edge", and two definitions drift.
+ *
+ * A `static` edge becoming `dynamic` is therefore a removed edge under the
+ * old type and an added edge under the new one, which is exactly what a
+ * consumer wants to see: it is a real architectural event, not an
+ * implementation detail.
+ *
+ * @param {{source: string, target: string, type: string}} edge
+ * @returns {string}
+ */
+export function edgeIdentityKey({ source, target, type }) {
+  return `${source}\0${target}\0${type}`;
+}
+
 /**
  * Computes the diff between two graph snapshots.
  *
- * Edge identity is `(source, target, type)` — a `static` edge becoming
- * `dynamic` is an added edge under the new type and a removed edge under the
- * old one, which is exactly what a consumer wants to see: it is a real
- * architectural event, not an implementation detail.
+ * Edge identity is `(source, target, type)` — see `edgeIdentityKey` above.
  *
  * @param {{projects: object[], dependencies: object[]}} baseline
  * @param {{projects: object[], dependencies: object[]}} head
@@ -282,13 +298,9 @@ export function computeDiff(baseline, head) {
   removedProjects.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
   changedProjects.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 
-  // Index edges by the (source, target, type) triple — the identity key.
-  const baselineEdges = new Map(
-    baseline.dependencies.map((e) => [`${e.source}\0${e.target}\0${e.type}`, e]),
-  );
-  const headEdges = new Map(
-    head.dependencies.map((e) => [`${e.source}\0${e.target}\0${e.type}`, e]),
-  );
+  // Index edges by the identity key — `edgeIdentityKey` above owns the triple.
+  const baselineEdges = new Map(baseline.dependencies.map((e) => [edgeIdentityKey(e), e]));
+  const headEdges = new Map(head.dependencies.map((e) => [edgeIdentityKey(e), e]));
 
   const addedEdges = [];
   const removedEdges = [];
@@ -410,8 +422,11 @@ export function diffCommand(
   // classifies as changes, compared here through the shared
   // `./snapshot-meta.mjs` so the two commands cannot disagree about them.
   // Each mismatch becomes a `coverage.notes` warning rather than a refusal:
-  // a provider migration, a cross-repository diff, or a policy change between
-  // baseline and head are all legitimate states a consumer must be told about.
+  // a provider migration, a cross-repository diff, a dirty-tree side, or a
+  // policy change between baseline and head are all legitimate states a
+  // consumer must be told about. The dirty-tree wording is the one `delta` and
+  // `change` emit over the same metadata — three commands, one sentence each,
+  // so a consumer reading any report reads the same caveat.
   const headProvenance = resolveProvenance(root);
   const headFingerprint = config ? computePolicyFingerprint(config) : null;
   const meta = compareSnapshotMetadata({
@@ -445,6 +460,19 @@ export function diffCommand(
     );
   }
 
+  if (meta.dirtyBaseline) {
+    coverage.notes.push(
+      "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
+        "claim about the commit it names",
+    );
+  }
+  if (meta.dirtyHead) {
+    coverage.notes.push(
+      "this run's working tree is dirty — the head side describes uncommitted state, not the " +
+        "commit HEAD names",
+    );
+  }
+
   if (meta.policyChanged === true) {
     // A policy change between baseline and head means every "introduced" or
     // "resolved" violation in the rule-impact analysis may be an artefact of