@ecoma-io/archkeep 0.13.0 → 0.14.0

package/src/commands/waivers.mjs

@@ -43,6 +43,8 @@ import { referenceTime } from "../governance/clock.mjs";
 import { isWaiver, remainingMs, waiverStatus } from "../governance/waiver.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatWaiversReport } from "../report/waivers-text.mjs";
+import { partitionUnownedCoverage } from "./coverage-acceptance.mjs";
+import { unownedGapWithoutRunConfiguration } from "./context.mjs";
 import { refuseIncompleteGraph } from "./drift.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { evaluateRun } from "../rules/index.mjs";
@@ -144,7 +146,10 @@ export function computeWaivers(suppressions, rawViolations, now = referenceTime(
  *   by the same three-way call `check` makes — `cli.mjs`'s `runWaivers`
  *   resolves `--config` against the working directory exactly as `runCheck`
  *   does, so the surface listed is the surface the law actually enforces.
- * @param {{now?: string}} [io] The injected clock.
+ * @param {{now?: string, policySource?: string|null}} [io] The injected
+ *   clock, and — from `cli.mjs`'s `runWaivers` — the workspace-relative path
+ *   the run's law actually resolved from, so the `coverage.unowned` matching
+ *   below subtracts the same configuration files `check` subtracts.
  * @returns {Promise<{status: "ok", waivers: object, report: {text: string, json: string}}>}
  * @throws {Error} whenever the run's law is malformed, or the tree has
  *   whole-file analysis failures — exit-3 class, the same posture `check` takes
@@ -155,15 +160,37 @@ export async function waiversCommand(commandContext, boundaryConfig, io = {}) {
   const now = io.now ?? referenceTime();
   const config = boundaryConfig;
 
+  // The policy's `coverage.unowned` acceptances, matched through the SAME
+  // partition `check` runs (`./coverage-acceptance.mjs`) so the two surfaces
+  // cannot disagree about what a row covers. This command is the surface the
+  // acceptances' REASONS live on: `check` states the accepted files and
+  // points here, this names each row with its reason and current coverage —
+  // the same division of labour the suppression table already has between
+  // `check`'s accepted-violations section and this command's rows.
+  const unownedCoverage = partitionUnownedCoverage({
+    rows: config?.coverage?.unowned ?? [],
+    unownedGap: unownedGapWithoutRunConfiguration(commandContext.unownedGap, [
+      io.policySource ?? null,
+      commandContext.options.tsConfig,
+    ]),
+    unclaimedFiles: commandContext.unclaimedGap.files,
+    tracked: commandContext.tracked,
+  });
+
   // A waiver surface over a tree it could not fully read is a lottery ticket,
   // not a surface: a file the analyzer never judged contributes no raw
   // violation, so every waiver that names it reads as stale and the report
   // says "covers nothing" about a finding the run never looked at. Refuse
   // loudly on whole-file failures, the same posture `impact`, `drift`, and
   // `history` take — "could not look" must never read as "looked and found
-  // nothing" (`./impact.mjs`'s refusal names the same silence).
+  // nothing" (`./impact.mjs`'s refusal names the same silence). A whole-file
+  // failure whose file a `coverage.unowned` row accepts is withdrawn first,
+  // exactly as `check` withdraws it (`./check.mjs`'s `acceptedUnclaimed`):
+  // its state is a recorded acceptance this very report is about to name,
+  // not a hole the run failed to look at.
   const notAnalyzed = analysis.failures
     .filter(isWholeFileFailure)
+    .filter(({ sourceFile }) => !unownedCoverage.acceptedFiles.has(sourceFile))
     .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
 
   if (notAnalyzed.length > 0) {
@@ -218,7 +245,30 @@ export async function waiversCommand(commandContext, boundaryConfig, io = {}) {
   };
 
   const context = { root, provider, marker, provenance: resolveProvenance(root) };
-  const result = { waivers, covered, expired, stale, suppressions, suppressed };
+  const result = {
+    waivers,
+    covered,
+    expired,
+    stale,
+    suppressions,
+    suppressed,
+    // The third surface, present only when the policy declares the channel —
+    // the same absent-is-a-decision key discipline `check`'s envelope keeps
+    // for `fitness`/`customRules`, so a workspace without the key gets a
+    // byte-identical envelope. Each row is the declared acceptance with how
+    // many unowned files it currently covers; a `covered: 0` row reads like
+    // a stale waiver above — dead weight this command surfaces and `check`
+    // refuses (`./check.mjs`'s dead-row block).
+    ...(config?.coverage === undefined
+      ? {}
+      : {
+          unownedAcceptances: unownedCoverage.rows.map(({ path, reason, files }) => ({
+            path,
+            reason,
+            covered: files.length,
+          })),
+        }),
+  };
 
   const envelope = jsonEnvelope({
     command: "waivers",

package/src/config.mjs

@@ -96,7 +96,8 @@
  *
  * The `.mjs`/`.js` and `.json` dialects share the same top-level key law: a
  * top-level export (or key) beyond `depConstraints`, `moduleBoundaryOptions`,
- * `boundarySuppressions`, `fitness` and `customRules` is rejected by name. The
+ * `boundarySuppressions`, `fitness`, `customRules` and `coverage` is rejected
+ * by name. The
  * `.mjs` dialect's tolerance for a helper export used to let a misspelled key
  * (`moduleBoundaryOptions` → `moduleBoundaryOption`) disappear into silence —
  * a typo'd law is a law that is not enforced, the exact silent direction this
@@ -557,6 +558,94 @@ function suppressionRowViolations(row, index) {
   return violations;
 }
 
+/**
+ * The keys a `coverage.unowned` row may carry. `reason` is not optional, for
+ * the same reason it is not optional on a suppression row above and on a
+ * native `coverage.exempt` row (`./providers/native/model.mjs`'s
+ * `exemptRowViolations`, whose semantics this row copies exactly): an
+ * accepted coverage hole with no reason written down is indistinguishable
+ * from coverage that quietly stopped being enforced.
+ */
+const COVERAGE_UNOWNED_KEYS = ["path", "reason"];
+
+/**
+ * One `coverage.unowned` row's problems, prefixed with its index.
+ *
+ * @param {unknown} row
+ * @param {number} index
+ * @returns {string[]}
+ */
+function coverageUnownedRowViolations(row, index) {
+  const at = `coverage.unowned[${index}]`;
+  if (!isPlainObject(row)) return [`${at}: must be an object, got ${describe(row)}`];
+
+  const violations = [];
+  if (typeof row.path !== "string" || row.path === "") {
+    violations.push(
+      `${at}.path: must be a non-empty glob over a workspace-relative path, matched with ` +
+        `\`path.posix.matchesGlob\`, got ${describe(row.path)}`,
+    );
+  } else {
+    const problem = globComplexityError(row.path);
+    if (problem) violations.push(`${at}.path: '${row.path}' ${problem}`);
+  }
+  if (typeof row.reason !== "string" || row.reason.trim() === "") {
+    violations.push(
+      `${at}.reason: must be a non-empty string — an accepted coverage hole with no reason ` +
+        `written down reads as coverage that is still enforced`,
+    );
+  }
+  for (const key of Object.keys(row)) {
+    if (!COVERAGE_UNOWNED_KEYS.includes(key)) {
+      violations.push(
+        `${at}.${key}: not a coverage.unowned field — expected one of ` +
+          COVERAGE_UNOWNED_KEYS.join(", "),
+      );
+    }
+  }
+  return violations;
+}
+
+/**
+ * Everything wrong with a policy's `coverage` key, as messages; empty when it
+ * is well-formed.
+ *
+ * The key holds exactly one field: `unowned`, an array of `{path, reason}`
+ * rows — a recorded acceptance of tracked files no project owns, for the Nx
+ * and Moon providers whose project model has no channel of its own for that
+ * decision (`../../../docs/reference/policy-schema.md`, "`coverage`"). A row
+ * is matched ONLY against files already decided to be unowned, so even a `**`
+ * row can never silence a verdict about an owned file — the same guarantee
+ * the native provider's `coverage.exempt` states
+ * (`./providers/native/coverage.mjs`). An empty `unowned` list is accepted
+ * for the reason an empty suppression list is: it accepts nothing, which is
+ * the direction that cannot hide anything.
+ *
+ * @param {unknown} value The parsed `coverage` value.
+ * @returns {string[]}
+ */
+function findCoverageViolations(value) {
+  if (!isPlainObject(value)) {
+    return [`coverage: must be an object carrying an 'unowned' array, got ${describe(value)}`];
+  }
+  const violations = [];
+  if (!Array.isArray(value.unowned)) {
+    violations.push(
+      `coverage.unowned: must be an array of {path, reason} rows, got ${describe(value.unowned)}`,
+    );
+  } else {
+    value.unowned.forEach((row, index) =>
+      violations.push(...coverageUnownedRowViolations(row, index)),
+    );
+  }
+  for (const key of Object.keys(value)) {
+    if (key !== "unowned") {
+      violations.push(`coverage.${key}: not a coverage field — expected 'unowned'`);
+    }
+  }
+  return violations;
+}
+
 /**
  * The grammar a custom rule's `name` is written in: lowercase letters and
  * digits, single `-` separators, nothing else.
@@ -863,8 +952,14 @@ export function findBoundaryConfigViolations(module, io = {}) {
   if (!isPlainObject(module)) return [`config: expected a module object, got ${describe(module)}`];
 
   const violations = [];
-  const { depConstraints, moduleBoundaryOptions, boundarySuppressions, fitness, customRules } =
-    module;
+  const {
+    depConstraints,
+    moduleBoundaryOptions,
+    boundarySuppressions,
+    fitness,
+    customRules,
+    coverage,
+  } = module;
   // F05: the resolution half of the governance block (`row-schema.mjs`'s
   // `io.resolve`) was validator-only until now — no production caller passed
   // one, so a row bound to a fitness rule that does not exist loaded and ran
@@ -909,6 +1004,16 @@ export function findBoundaryConfigViolations(module, io = {}) {
     violations.push(...findCustomRuleViolations(customRules, io));
   }
 
+  // The unowned-file acceptances — the sixth top-level law, shaped here and
+  // matched by `./commands/coverage-acceptance.mjs` against files already
+  // decided to be unowned, never against owned ones. Absent means "no
+  // acceptance recorded"; present and malformed is refused loudly, because a
+  // row this reader could not understand is an acceptance that would not
+  // apply while the policy still says it does.
+  if (coverage !== undefined) {
+    violations.push(...findCoverageViolations(coverage));
+  }
+
   // Absent means "nothing is suppressed", which is the only default that fails
   // toward reporting — unlike the eight options above, where a missing value
   // would be a second copy of something ESLint also reads and this module has
@@ -996,8 +1101,15 @@ export function findBoundaryConfigViolations(module, io = {}) {
  * general "ignore unknown" rule, which is exactly the leniency this file's
  * header argues a JSON object must not get). `fitness` is the fourth: the
  * boundary dialect's key for the fitness-functions list, validated as an array
- * of fitness rows. `customRules` is the fifth and newest — the declared rules
+ * of fitness rows. `customRules` is the fifth — the declared rules
  * this engine did not write, validated as an array of custom-rule rows.
+ * `coverage` is the sixth and newest: the recorded acceptances of unowned
+ * files on an Nx or Moon workspace (`findCoverageViolations` above owns the
+ * shape). On a native tree the key is refused — `archkeep.json`'s own
+ * `coverage.exempt` is that provider's one channel for the same decision —
+ * and the refusal lives in `./commands/policy.mjs`'s `resolvePolicy` and
+ * `./providers/native/model.mjs`'s inline-policy check, because only they
+ * know which provider is reading.
  *
  * The name says `.json` and the list binds both file dialects: `loadModulePolicy`
  * runs the same check over an ES module's exports, which is what makes a
@@ -1010,6 +1122,7 @@ const JSON_POLICY_KEYS = [
   "boundarySuppressions",
   "fitness",
   "customRules",
+  "coverage",
 ];
 
 /**
@@ -1086,7 +1199,7 @@ export function policyKeyViolations(parsed, { allowSchema }) {
  *   inline one.
  * @param {string[]} [extraViolations] Violations the caller already found that
  *   `findBoundaryConfigViolations` does not check on its own.
- * @returns {{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[] }}
+ * @returns {{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object }}
  *   `fitness` and `customRules` are present only when the config declares
  *   them — a workspace without one carries no key, the same "absent is a
  *   decision" posture `cli.mjs`'s `check` uses for a missing
@@ -1109,6 +1222,7 @@ export function policyFrom(parsed, sourceLabel, extraViolations = []) {
     suppressions: parsed.boundarySuppressions ?? [],
     ...(parsed.fitness === undefined ? {} : { fitness: parsed.fitness }),
     ...(parsed.customRules === undefined ? {} : { customRules: parsed.customRules }),
+    ...(parsed.coverage === undefined ? {} : { coverage: parsed.coverage }),
   };
 }
 
@@ -1125,7 +1239,7 @@ export function policyFrom(parsed, sourceLabel, extraViolations = []) {
  * legitimate namespace to share a helper in gave a typo the same silence.
  *
  * @param {string} path Absolute path of the config file.
- * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[] }>}
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object }>}
  * @throws {Error} when the file is missing, unloadable, or malformed.
  */
 async function loadModulePolicy(path) {
@@ -1151,7 +1265,7 @@ async function loadModulePolicy(path) {
  * @param {{readFile?: (path: string, encoding: "utf8") => Promise<string>}} [io]
  *   Injectable read, defaulting to `node:fs/promises`' `readFile` — the only
  *   code in this function that reaches outside the process.
- * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[] }>}
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object }>}
  * @throws {Error} when the file is missing, unreadable, not valid JSON, or
  *   malformed — either by `findBoundaryConfigViolations`' rules or by carrying
  *   a top-level key none of those rules knows about.
@@ -1198,7 +1312,7 @@ async function loadJsonPolicy(path, { readFile = readFileFromDisk } = {}) {
  * @param {string} path Absolute path of the config file.
  * @param {{readFile?: (path: string, encoding: "utf8") => Promise<string>}} [io]
  *   Injectable read, used only by the `.json` dialect — see `loadJsonPolicy`.
- * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], notes?: string[] }>}
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, notes?: string[] }>}
  *   `suppressions` is `[]` when the config declares none. `notes` is present
  *   only under the ESLint dialect, and only when `./eslint-config.mjs` has
  *   something worth telling a reader about which entry it bound — see
@@ -1250,8 +1364,12 @@ export async function loadBoundaryConfigFile(path, io = {}) {
       // from (see this module's header). Never populated under this dialect —
       // `policyFrom` already resolves that to `[]` since the object above
       // states no `boundarySuppressions` key, and it leaves `customRules`
-      // absent for the same reason, the header's own distinction between an
-      // absent law and an empty one.
+      // and `coverage` absent for the same reason, the header's own
+      // distinction between an absent law and an empty one: a flat config's
+      // one rule entry is a constraint table and its options, with nowhere to
+      // name a rule artifact or an unowned-file acceptance
+      // (`../../../docs/reference/policy-schema.md`'s dialect table names both
+      // gaps on the consumer-facing side).
       ...(note !== undefined ? { notes: [note] } : {}),
     };
   }
@@ -1279,7 +1397,7 @@ export async function loadBoundaryConfigFile(path, io = {}) {
  *   misconfigured tool.
  * @param {{readFile?: (path: string, encoding: "utf8") => Promise<string>}} [io]
  *   Forwarded to `loadBoundaryConfigFile` — see there.
- * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], notes?: string[] }>}
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object, notes?: string[] }>}
  * @throws {Error} as `loadBoundaryConfigFile`.
  */
 export async function loadBoundaryConfig(workspaceRoot, boundaryConfig, io = {}) {

package/src/lsp/boundary-config.mjs

@@ -62,7 +62,7 @@ import { ARCHKEEP_MODEL_FILE } from "../providers/native/model.mjs";
  *
  * @param {string} path Absolute path of the config file.
  * @param {string|number} revision Busts the ESM module cache across edits.
- * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[] }>}
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object }>}
  * @throws {Error} when the file is missing, unloadable, or malformed.
  */
 async function readModulePolicy(path, revision) {
@@ -86,7 +86,7 @@ async function readModulePolicy(path, revision) {
  * @param {(path: string, encoding: "utf8") => Promise<string>} readFile
  *   Injected so a test can drive this without a real file — see
  *   `readBoundaryConfig` below.
- * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[] }>}
+ * @returns {Promise<{ depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object }>}
  * @throws {Error} when the file is missing, unreadable, not valid JSON, or
  *   malformed — either by `../config.mjs`'s `findBoundaryConfigViolations` or
  *   by carrying a top-level key none of those rules knows about.
@@ -144,14 +144,19 @@ async function readJsonPolicy(path, readFile) {
  * @param {{readFile?: (path: string, encoding: "utf8") => Promise<string>}} [io]
  *   Injectable read, used only by the `.json` dialect, defaulting to
  *   `node:fs/promises`'s `readFile`.
- * @returns {Promise<{depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[]}>}
+ * @returns {Promise<{depConstraints: object[], options: object, suppressions: object[], fitness?: object[], customRules?: object[], coverage?: object}>}
  *   `suppressions` is `[]` when the config declares none; `fitness` and
  *   `customRules` are present only when the policy declares them, the same
  *   absent-is-a-decision shape `../config.mjs`'s `policyFrom` returns to
  *   every other face. This server READS both and evaluates neither — a
  *   fitness function and a custom rule are per-run workspace judgments, not
  *   per-file diagnostics — so what it owes them is to load them and to fail
- *   loudly on a row it cannot read.
+ *   loudly on a row it cannot read. `coverage` rides the same bargain one
+ *   key further: unowned-file acceptance is a whole-run coverage decision
+ *   (`../commands/coverage-acceptance.mjs`), never a per-file diagnostic, so
+ *   the server's whole duty to the key is to ACCEPT a config carrying it —
+ *   the same `policyKeyViolations` the CLI runs — rather than reject in the
+ *   editor a law `check` enforces.
  * @throws {Error} when `boundaryConfig` names the ESLint flat-config dialect
  *   or a legacy `.eslintrc*` file (this reader does not read either yet — see
  *   above), or — for a dialect it does read — when the file is missing,

package/src/providers/native/model.mjs

@@ -520,6 +520,23 @@ export function findNativeModelViolations(raw) {
           (message) => `boundaryConfig.${message}`,
         ),
       );
+      // The policy's `coverage` key is an Nx/Moon channel, refused here BY
+      // NAME on the one provider that already has its own: this very file's
+      // `coverage.exempt` is where a native tree records an unowned-file
+      // acceptance, and two channels for one decision on one tree is how
+      // copies drift (the same posture as the `.moon`-beside-`archkeep.json`
+      // refusal in `../../commands/context.mjs`'s `requireSingleProjectModel`).
+      // The file-dialect spelling of the same mistake — a native tree whose
+      // boundaryConfig FILE declares `coverage` — is refused by
+      // `../../commands/policy.mjs`'s `resolvePolicy`, which is the first
+      // point that knows both the provider and the loaded policy.
+      if ("coverage" in raw.boundaryConfig) {
+        violations.push(
+          `boundaryConfig.coverage: not accepted on a native workspace — this tree records ` +
+            `unowned-file acceptances on archkeep.json's own coverage.exempt, and a second ` +
+            `channel for the same decision is a copy that will drift. Move the rows there`,
+        );
+      }
     } else if (typeof raw.boundaryConfig !== "string") {
       violations.push(
         `boundaryConfig: must be a string (a filename) or an object (an inline policy), got ` +

package/src/report/delta-text.mjs

@@ -0,0 +1,183 @@
+/**
+ * The terminal report for the `delta` command: how boundary violations moved
+ * between a captured baseline and the current tree, both re-judged under the
+ * current law (`../commands/delta.mjs`).
+ *
+ * Sections render only when they have content — introduced (with waived
+ * annotations), resolved, unchanged (with the occurrences-reduced note where
+ * one applies), unknown (with the reason each identity could not be stated),
+ * and the unresolvable-import block — and the summary line always states what
+ * was compared: base and head identity, record and project counts, and the
+ * bucket totals. "No introduced violations" is a claim about a comparison the
+ * reader can verify, never silence (`../../../../AGENTS.md`).
+ *
+ * `coverage.notes` — the policy-changed, dirty-tree, and provenance warnings
+ * `../commands/delta.mjs` pushes there — fold into the report as their own
+ * lines, so a note that rides the JSON envelope also reaches the terminal.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`./README.md`).
+ */
+
+/** A side's identity for prose: its commit prefix, or an honest absence. */
+function describeOrigin(provenance) {
+  if (!provenance || typeof provenance.commit !== "string") return "unverified origin";
+  const dirty = provenance.dirty ? ", dirty" : "";
+  return `${provenance.commit.slice(0, 8)}${dirty}`;
+}
+
+/** One classified violation entry as its report lines. */
+function violationLines(entry) {
+  const source = entry.sourceProject ?? "(unattributed)";
+  const arrow = entry.targetIsSpecifier ? "⇢" : "→";
+  const counts = `${entry.baseCount} at base, ${entry.headCount} at head`;
+  const waived = entry.waived === true ? "  [waived]" : "";
+  const lines = [`  ${source} ${arrow} ${entry.target}  ${entry.messageId}  (${counts})${waived}`];
+  if (entry.note !== undefined) lines.push(`    ${entry.note}`);
+  const sites = entry.headSites.length > 0 ? entry.headSites : entry.baseSites;
+  for (const site of sites) {
+    lines.push(`    at ${site.file}:${site.line}:${site.column}`);
+  }
+  return lines;
+}
+
+/** One classified unresolvable-record entry as its report lines. */
+function unresolvableLines(entry) {
+  const source = entry.sourceProject ?? "(unattributed)";
+  const counts = `${entry.baseCount} at base, ${entry.headCount} at head`;
+  const lines = [`  ${source} ⇢ ${entry.specifier}  (${entry.kind || "unknown kind"}; ${counts})`];
+  if (entry.note !== undefined) lines.push(`    ${entry.note}`);
+  const sites = entry.headSites.length > 0 ? entry.headSites : entry.baseSites;
+  for (const site of sites) {
+    lines.push(`    at ${site.file}:${site.line}:${site.column}`);
+  }
+  return lines;
+}
+
+/** One unknown entry — the reason is the load-bearing half. */
+function unknownLines(entry) {
+  return [`  ? ${entry.reason}`];
+}
+
+/**
+ * One classification bucket as a section, or nothing when it is empty.
+ *
+ * @param {string} heading Rendered above the entries, already carrying its count.
+ * @param {string[][]} entryLines
+ * @returns {string[]}
+ */
+function section(heading, entryLines) {
+  if (entryLines.length === 0) return [];
+  return [heading, ...entryLines.flat()];
+}
+
+/**
+ * The whole delta report.
+ *
+ * @param {{delta: object, coverage: object}} input `delta` is
+ *   `../commands/delta.mjs`'s result payload; `coverage` its coverage block.
+ * @returns {string}
+ */
+export function formatDeltaReport({ delta, coverage }) {
+  const sections = [];
+  const { baseline, head, summary, violations, unresolvable } = delta;
+
+  sections.push(
+    `baseline  ${baseline.path} — ${describeOrigin(baseline.provenance)}, ` +
+      `${baseline.records} record${baseline.records === 1 ? "" : "s"}, ` +
+      `${baseline.projects} project${baseline.projects === 1 ? "" : "s"}`,
+  );
+  sections.push(
+    `head      ${describeOrigin(head.provenance)}, ` +
+      `${head.records} record${head.records === 1 ? "" : "s"}, ` +
+      `${head.projects} project${head.projects === 1 ? "" : "s"}`,
+  );
+
+  for (const note of coverage.notes ?? []) {
+    sections.push(`⚠ ${note}`);
+  }
+
+  const introducedWord = summary.introduced === 1 ? "violation" : "violations";
+  sections.push(
+    ...section(
+      `⚠ ${summary.introduced} introduced ${introducedWord}` +
+        (summary.introducedWaived > 0
+          ? ` (${summary.introducedWaived} waived — reported, not gating)`
+          : ""),
+      violations.introduced.map(violationLines),
+    ),
+  );
+  sections.push(
+    ...section(
+      `✔ ${summary.resolved} resolved ${summary.resolved === 1 ? "violation" : "violations"}`,
+      violations.resolved.map(violationLines),
+    ),
+  );
+  sections.push(
+    ...section(
+      `= ${summary.unchanged} unchanged ${summary.unchanged === 1 ? "violation" : "violations"}`,
+      violations.unchanged.map(violationLines),
+    ),
+  );
+  sections.push(
+    ...section(
+      `? ${summary.unknown} unclassifiable ${summary.unknown === 1 ? "item" : "items"}`,
+      violations.unknown.map(unknownLines),
+    ),
+  );
+
+  const unresolvableTotal =
+    summary.unresolvable.introduced +
+    summary.unresolvable.resolved +
+    summary.unresolvable.unchanged +
+    summary.unresolvable.unknown;
+  if (unresolvableTotal > 0) {
+    sections.push(
+      `unresolvable imports (carried, never counted as violations — no rule reached a verdict ` +
+        `about them)`,
+    );
+    sections.push(
+      ...section(
+        `  + ${summary.unresolvable.introduced} introduced`,
+        unresolvable.introduced.map(unresolvableLines),
+      ),
+    );
+    sections.push(
+      ...section(
+        `  - ${summary.unresolvable.resolved} resolved`,
+        unresolvable.resolved.map(unresolvableLines),
+      ),
+    );
+    sections.push(
+      ...section(
+        `  = ${summary.unresolvable.unchanged} unchanged`,
+        unresolvable.unchanged.map(unresolvableLines),
+      ),
+    );
+    sections.push(
+      ...section(
+        `  ? ${summary.unresolvable.unknown} unclassifiable`,
+        unresolvable.unknown.map(unknownLines),
+      ),
+    );
+  }
+
+  // The closing claim always states what was compared, so an empty delta is a
+  // verifiable statement rather than silence.
+  const compared =
+    `compared baseline ${describeOrigin(baseline.provenance)} ` +
+    `(${baseline.records} record${baseline.records === 1 ? "" : "s"}) against head ` +
+    `${describeOrigin(head.provenance)} (${head.records} record${head.records === 1 ? "" : "s"}, ` +
+    `${coverage.analyzedFiles} analyzed file${coverage.analyzedFiles === 1 ? "" : "s"}, ` +
+    `${coverage.projects} project${coverage.projects === 1 ? "" : "s"})`;
+  if (summary.introduced === 0) {
+    sections.push(`✔ no introduced violations — ${compared}`);
+  } else {
+    sections.push(
+      `${summary.introduced - summary.introducedWaived} introduced ${introducedWord} not ` +
+        `waived — ${compared}`,
+    );
+  }
+
+  return sections.join("\n");
+}

package/src/report/explain-text.mjs

@@ -15,6 +15,10 @@
  * - the constraint row(s) that matched (which rule applied)
  * - the verdict (violation or allowed)
  * - the message, when there is one (what the verdict means in prose)
+ * - for a violation: the allowed direction when the governing row states one,
+ *   and a remediation line that is the author's declared guidance verbatim —
+ *   or, when none is declared, an explicit pointer at the constraint row and
+ *   its `decisionRef`, never a fix this renderer composed
  * - coverage information (whether this explanation is complete)
  *
  * This module decides nothing. A formatter that filtered would be a rule
@@ -131,8 +135,31 @@ export function formatExplainReport({ explanation, coverage }) {
         if (v.constraint?.description) {
           sections.push(`${DETAIL}rule         ${v.constraint.description}`);
         }
+        // The allowed direction, verbatim from the governing row when it
+        // states one. A `notDependOnLibsWithTags` row states no allowed list,
+        // and computing its complement here would be this renderer inventing
+        // a direction the law never wrote — the constraint line above is the
+        // honest answer there, so no line is printed.
+        if (Array.isArray(v.constraint?.onlyDependOnLibsWithTags)) {
+          sections.push(
+            `${DETAIL}allowed      ${formatTags(v.constraint.onlyDependOnLibsWithTags)}`,
+          );
+        }
+        // The remediation line is always printed for a violation: the
+        // author's declared guidance verbatim, or an explicit pointer at
+        // where guidance lives — never a fix this renderer composed, and
+        // never silence a reader could mistake for "nothing to consult".
         if (v.constraint?.remediation) {
           sections.push(`${DETAIL}remediation  ${v.constraint.remediation}`);
+        } else if (v.constraint) {
+          const ref = v.constraint.decisionRef
+            ? ` and its decisionRef ${v.constraint.decisionRef}`
+            : "";
+          sections.push(`${DETAIL}remediation  none declared — consult the constraint row${ref}`);
+        } else {
+          sections.push(
+            `${DETAIL}remediation  none declared — no depConstraints row drives this check`,
+          );
         }
       }
     } else {

package/src/report/sarif.mjs

@@ -680,6 +680,31 @@ export function sarifCoverageGapNotification(gap) {
       },
     };
   }
+  // The accepted counterpart: the same bounded sample, saying the state is a
+  // recorded acceptance (`coverage.unowned`) rather than an open question —
+  // still a warning, because an accepted hole is still a hole, and this face
+  // must not be the one that stops saying so.
+  if (gap.kind === "accepted-unowned-files") {
+    const files = gap.files ?? [];
+    const languages = gap.languages ?? [];
+    const spans = languages.length > 0 ? ` (${languages.join(", ")})` : "";
+    const shown = files.slice(0, UNOWNED_SAMPLE_LIMIT);
+    const remaining = files.length - shown.length;
+    const listed =
+      shown.length > 0
+        ? `: ${shown.join(", ")}${remaining > 0 ? `, and ${remaining} more` : ""}`
+        : "";
+    return {
+      level: "warning",
+      message: {
+        text:
+          `${files.length} tracked analyzable file${files.length === 1 ? "" : "s"}${spans} ` +
+          `owned by no project — accepted as coverage holes by the policy's coverage.unowned, ` +
+          `so no boundary verdict in this run covers ` +
+          `${files.length === 1 ? "it" : "them"}${listed}`,
+      },
+    };
+  }
   return {
     level: "warning",
     message: {