@ecoma-io/archkeep 0.21.0 → 0.22.1

package/src/commands/delta.mjs

@@ -23,8 +23,12 @@
  * 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"):
+ * Refusals — a delta that could not honestly classify must never read as
+ * "no change". Incomplete CURRENT coverage on the compare side returns the
+ * structured no-verdict envelope `./coverage-verdict.mjs` builds (#608) —
+ * status "no-verdict", exit 3, a `coverage` block naming every file and site
+ * the run could not judge — where a parser and `--output` can read it; the
+ * rest are throws, exit 3 upstream:
  * - a baseline that cannot be read, parsed, or holds a foreign schemaVersion
  *   (`./delta-snapshot.mjs`'s loader owns those);
  * - a provider mismatch between baseline and this run (`providerMismatch`) —
@@ -32,8 +36,8 @@
  *   across two different project models is not trustworthy: the same tree
  *   attributed to different projects would classify a rename as an
  *   introduced/resolved pair the code does not contain;
- * - incomplete CURRENT coverage — a delta over a half-analyzed head is not a
- *   verdict, the same posture `check` takes on `unchecked` files;
+ * - incomplete coverage on the CAPTURE side (`refuseUnjudgeableHead`), where
+ *   there is no envelope to withhold — a baseline write has no verdict;
  * - an Nx workspace with polyglot manifests but no plugin registration — the
  *   same silently-under-representing graph `graph`/`diff` refuse.
  *
@@ -62,7 +66,11 @@
  */
 import { createRequire } from "node:module";
 
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { stripTrailingSlashes } from "../path-util.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import {
@@ -97,6 +105,7 @@ import {
 } from "./delta-snapshot.mjs";
 import { computeDiff } from "./diff.mjs";
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
 
@@ -105,20 +114,21 @@ const require = createRequire(import.meta.url);
 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.
+ * Refuses the unregistered-plugin head state no delta side may be built over:
+ * on an Nx workspace whose `nx.json` does not register this plugin but whose
+ * tracked files include polyglot manifests under project roots.
  *
  * 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.
+ * over the same head state — a graph that under-represents the tree 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.
+ * @throws {Error} on the unregistered-plugin graph.
  */
-export function refuseUnjudgeableHead(commandContext, activity) {
+export function refusePluginGapHead(commandContext, activity) {
   const { provider, pluginGap } = commandContext;
   if (provider === "nx" && !pluginGap.registered && pluginGap.manifests.length > 0) {
     throw new Error(
@@ -130,11 +140,45 @@ export function refuseUnjudgeableHead(commandContext, activity) {
         `manifests if they are not in use.`,
     );
   }
+}
+
+/**
+ * Refuses, as a throw, the two head states no delta side may be built over:
+ * the unregistered-plugin graph (`refusePluginGapHead`) and incomplete
+ * analysis coverage.
+ *
+ * The coverage half stayed a throw through #602's unification of the
+ * graph-family refusal, and it stays one here — but only for the CAPTURE
+ * side: `captureDelta` writes a baseline, and a write that cannot be honest
+ * has no verdict to withhold, so stderr is the only face it has. The compare
+ * side (`deltaCommand`, `changeCommand`) refuses coverage through
+ * `./coverage-verdict.mjs`'s structured envelope (#608) instead and calls only
+ * `refusePluginGapHead`, so a withheld verdict reaches a parser and
+ * `--output` in-band.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {string} activity Which mode is refusing, for the message.
+ * @throws {Error} on either condition.
+ */
+export function refuseUnjudgeableHead(commandContext, activity) {
+  refusePluginGapHead(commandContext, activity);
   const notAnalyzed = commandContext.analysis.failures.filter(isWholeFileFailure);
-  if (notAnalyzed.length > 0) {
+
+  const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
+  if (notAnalyzed.length > 0 || blindSpotCount > 0) {
     throw new Error(
-      `archkeep: cannot ${activity} — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so the evidence would ` +
+      `archkeep: cannot ${activity} — ` +
+        [
+          notAnalyzed.length > 0
+            ? `${notAnalyzed.length} file${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed`
+            : null,
+          blindSpotCount > 0
+            ? `${blindSpotCount} import site${blindSpotCount === 1 ? "" : "s"} could not be resolved`
+            : null,
+        ]
+          .filter(Boolean)
+          .join(", ") +
+        `, so the evidence would ` +
         `miss violations living there and a later classification would misread the gap as a ` +
         `code change. Fix the unanalyzed files and re-run.`,
     );
@@ -181,14 +225,7 @@ export function captureDelta(commandContext, { config }) {
       complete: true,
       analyzedFiles: analysis.analyzed,
       notAnalyzed: [],
-      blindSpots: analysis.failures
-        .filter((failure) => !isWholeFileFailure(failure))
-        .map(({ sourceFile, line, column, reason }) => ({
-          file: sourceFile,
-          line,
-          column,
-          reason,
-        })),
+      blindSpots: blindSpotRows(analysis.failures),
     },
     graph,
     records: analysis.imports,
@@ -387,15 +424,21 @@ const short = (fingerprint) =>
  *   `loadIntent`; absent intent ⇒ no ids, an in-band note says so), and the
  *   custom-rule host's two injectable seams, passed through to
  *   `customRulesForDelta`.
- * @returns {Promise<{status: "ok"|"findings"|"no-verdict", delta: object,
+ * @returns {Promise<{status: "ok"|"findings"|"no-verdict", delta?: object,
  *   coverage: object,
- *   eventWrite: {id: string, duplicate: boolean}|null,
- *   report: {text: string, json: string, sarif: string}}>} `delta` carries
+ *   eventWrite?: {id: string, duplicate: boolean}|null,
+ *   report: {text: string, json: string, sarif?: string}}>} `delta` carries
  *   the additive `classifications`/`affected` fields (design §1); `eventWrite`
  *   is `null` unless `eventOut` was given, then the store's answer for the
- *   event that was (or already was) recorded.
+ *   event that was (or already was) recorded. `status: "no-verdict"` from the
+ *   coverage refusal (#608) carries neither `delta` nor `eventWrite` — the
+ *   comparison was withheld before any event work, and the envelope's
+ *   `coverage` block plus its `decision.reason` are the whole answer; the
+ *   report then has no `sarif` face (there are no findings to render).
  * @throws {Error} on every refusal the module header lists, and on a
  *   custom-rule LOAD failure (`./custom-rules.mjs` argues the split).
+ *   Incomplete head coverage returns the structured no-verdict envelope
+ *   instead of throwing (#608); the unregistered-plugin graph keeps its throw.
  */
 export async function deltaCommand(
   baselinePath,
@@ -411,7 +454,22 @@ export async function deltaCommand(
 ) {
   const { root, provider, marker, graph, analysis, tracked } = commandContext;
 
-  refuseUnjudgeableHead(commandContext, "compute a delta");
+  // The plugin-gap refusal stays a throw; the coverage refusal returns the one
+  // structured envelope `./coverage-verdict.mjs` builds (#608): a verdict
+  // withheld because the run could not read the tree belongs in-band, where a
+  // parser and `--output` can read it — the same contract the graph family has
+  // run since #602. The capture side keeps the throw (`refuseUnjudgeableHead`
+  // above), because a baseline write has no envelope to withhold.
+  refusePluginGapHead(commandContext, "compute a delta");
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({
+      command: "delta",
+      commandContext,
+      what: "computing a delta",
+      decision: true,
+    });
+  }
   if (!config) {
     throw new Error(
       "archkeep: cannot compute a delta without a boundary config — both sides are re-judged " +
@@ -630,7 +688,13 @@ export async function deltaCommand(
   };
   const evolution = classifyDeltaEvolution(deltaPayload, {
     projects: structural.projects,
-    edges: structural.edges,
+    // The raw triples, not `structural.edges` (the mapped identity strings):
+    // `classifyEvolution` owns the spelling and takes the triples. The
+    // envelope's `structural` and the event's `observed` keep the mapped
+    // strings this run derived above — one mapping per command, and the
+    // classification's `affected.boundaries` comes out under the same
+    // spelling because it is mapped inside `classifyEvolution` itself.
+    edges: { added: structuralDiff.addedEdges, removed: structuralDiff.removedEdges },
     codeDrift,
   });
 
@@ -683,9 +747,7 @@ export async function deltaCommand(
     analyzedFiles: analysis.analyzed,
     imports: analysis.imports.length,
     notAnalyzed: [],
-    blindSpots: analysis.failures
-      .filter((failure) => !isWholeFileFailure(failure))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    blindSpots: blindSpotRows(analysis.failures),
     notes,
   };
 

package/src/commands/diff.mjs

@@ -40,9 +40,9 @@
  */
 import { readFileSync } from "node:fs";
 
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
 import { computeRuleImpact } from "./edge-constraints.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { SCHEMA_VERSION } from "../report/json.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatDiffReport } from "../report/diff-text.mjs";
@@ -349,11 +349,14 @@ export function computeDiff(baseline, head) {
  *   When omitted, reads from the real filesystem. `config` is the loaded
  *   boundary config; when provided, rule-impact analysis is computed alongside
  *   the structural diff.
- * @returns {{status: "ok"|"no-verdict", diff: object, coverage: object,
- *   report: {text: string, json: string}}}
- * @throws {Error} when the baseline cannot be read or is incomplete, when
- *   the head is incomplete, or when an Nx workspace has polyglot manifests
- *   but the plugin is not registered.
+ * @returns {{status: "ok"|"no-verdict", diff?: object, coverage: object,
+ *   report: {text: string, json: string}}} `diff` is absent under
+ *   `status: "no-verdict"` — the coverage refusal (#608) withholds the
+ *   comparison, and the envelope's `coverage` block is the whole answer.
+ * @throws {Error} when the baseline cannot be read or is incomplete, or when
+ *   an Nx workspace has polyglot manifests but the plugin is not registered
+ *   (the inline throw in the body). An incomplete head returns the
+ *   structured no-verdict envelope instead of throwing (#608).
  */
 export function diffCommand(
   baselinePath,
@@ -379,19 +382,18 @@ export function diffCommand(
   // is a caller error, not a workspace fact, and it should name the file.
   const baseline = readBaseline(baselinePath);
 
-  // Refuse an incomplete head — same reasoning as the incomplete baseline
-  // refusal: every "added" or "removed" entry would be ambiguous.
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: the head graph has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every "added" or ` +
-        `"removed" entry in the diff would be ambiguous between a real change and a coverage ` +
-        `gap. Fix the unanalyzed files and re-run.`,
-    );
+  // Refuse an incomplete head through the one structured contract
+  // `./coverage-verdict.mjs` builds (#608): the diff is withheld in-band —
+  // status "no-verdict", exit 3, a `coverage` block naming every file and
+  // site the run could not judge — where a parser and `--output` can read it.
+  // The reasoning is the incomplete-baseline refusal's: every "added" or
+  // "removed" entry would be ambiguous. That baseline refusal stays a throw —
+  // `parseBaseline` above throws it through the default reader — because a
+  // baseline nobody captured correctly is a caller error about a file, not a
+  // coverage fact about THIS tree.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "diff", commandContext, what: "diffing the head graph" });
   }
 
   const head = buildHeadSnapshot(commandContext);
@@ -404,9 +406,7 @@ export function diffCommand(
     analyzedFiles: commandContext.analysis.analyzed,
     imports: commandContext.analysis.imports.length,
     notAnalyzed: [],
-    blindSpots: commandContext.analysis.failures
-      .filter((f) => !isWholeFileFailure(f))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    blindSpots: completeness.blindSpots,
     notes: [],
   };
 
@@ -417,6 +417,12 @@ export function diffCommand(
       projects: baseline.projects.length,
       edges: baseline.dependencies.length,
       toolVersion: baseline.toolVersion,
+      // The provenance the baseline itself recorded — which commit, remote,
+      // and dirtiness the captured side names (#609). The head side's own
+      // provenance rides the envelope's `workspace.provenance`; without the
+      // baseline's, a consumer could not tell WHICH revision the empty or
+      // non-empty diff is measured against.
+      provenance: baseline.provenance ?? null,
     },
     head: { projects: head.projects.length, edges: head.dependencies.length },
     addedProjects: diff.addedProjects,
@@ -525,8 +531,9 @@ export function diffCommand(
     // no depConstraints violations were introduced or resolved on the changed
     // edges. Run `check` for the complete verdict.
     coverage.notes.push(
-      "per-edge rule-impact covers only depConstraints (3 of 15 violation types). " +
-        "A dependency with no rule-impact may still violate npm-ban, circular-dependency, " +
+      "per-edge rule-impact covers only depConstraints (3 of 15 violation types; standing " +
+        "edges adjacent to a tags-changed project are re-judged under both sides' tags). A " +
+        "dependency with no rule-impact may still violate npm-ban, circular-dependency, " +
         "lazy-load, or other rules that require import-site details. Run check for the " +
         "complete verdict.",
     );

package/src/commands/discover.mjs

@@ -20,18 +20,23 @@
  *
  * ## The empty-result invariant
  *
- * A workspace the run could not fully read (`notAnalyzed` non-empty) returns
- * `status: "no-verdict"` → exit 3, the same refusal `graph`/`drift` make:
- * every missing edge would be ambiguous between "gone" and "never seen".
- * An Nx workspace with polyglot manifests and no plugin registration is
- * refused the same way `graph` refuses it — the graph would silently
- * under-represent the real architecture, and a candidate derived from it
- * would be a fabrication wearing a proposal's name.
+ * Completeness comes from `./coverage-verdict.mjs`'s shared constructor —
+ * the same three-axis law (no whole-file failure, no unjudged blind spot,
+ * at least one file analyzed) that `graph` and `check` judge completeness
+ * over. The graph-family restatement this replaces is how the zero-analysis
+ * axis went missing here (#619).
  *
  * A workspace with zero projects is NOT a refusal: it is the empty proposal
  * with `unknown: true` (`evaluateDiscovery`'s contract), because zero observed
  * projects is a complete observation — the honest answer is "nothing to
- * propose", not a fabricated candidate set.
+ * propose", not a fabricated candidate set. The constructor's zero-analysis
+ * clause is overridden for this case: if there is nothing to observe, the
+ * observation is complete.
+ *
+ * An Nx workspace with polyglot manifests and no plugin registration is
+ * refused the same way `graph` refuses it — the graph would silently
+ * under-represent the real architecture, and a candidate derived from it
+ * would be a fabrication wearing a proposal's name.
  *
  * ## Determinism
  *
@@ -40,10 +45,11 @@
  * byte-identical text and JSON — the same promise `graph`'s snapshots make,
  * which is what lets a consumer `diff` two proposals meaningfully.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
 import { evaluateDiscovery } from "../governance/discovery-proposal.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatDiscoverReport } from "../report/discover-text.mjs";
+import { coverageIncompleteReasons } from "../verdict.mjs";
+import { coverageVerdict } from "./coverage-verdict.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { refuseIncompleteGraph } from "./drift.mjs";
@@ -127,40 +133,74 @@ export function discoverCommand(commandContext, { propose = false } = {}) {
 
   refuseIncompleteGraph(commandContext);
 
-  const notAnalyzed = analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
   const observed = buildObserved(commandContext);
 
   const proposal = propose ? evaluateDiscovery(observed) : null;
 
+  // The completeness verdict is the shared constructor's, not this file's:
+  // restating the axes here is how the `analyzed > 0` term went missing from
+  // this face (#619 — a run that judged no file at all used to report `ok` /
+  // `complete: true` / exit 0, byte-for-byte the envelope a clean workspace
+  // gets). `coverageVerdict` owns the one law — no whole-file failure, no
+  // unjudged site, at least one file analyzed — and the same return shape
+  // the envelope and the text face both read.
+  //
+  // One override: a workspace with zero projects is a complete observation
+  // (there is nothing to observe), so the zero-analysis clause does not
+  // withhold from it. `evaluateDiscovery`'s contract returns `unknown: true`
+  // over an empty project list, and that answer is honest — it does not
+  // claim completeness over nothing.
+  const verdict = coverageVerdict(commandContext);
+  const hasProjects = observed.projects.length > 0;
+  const { complete, status, exitCode } = verdict;
+  // When there are no projects, override the zero-analysis withdrawal: an
+  // empty observation is a complete observation, and the `unknown` proposal
+  // is the honest answer.
+  const effectiveComplete = hasProjects ? complete : true;
+  const effectiveStatus = hasProjects ? status : "ok";
+  const effectiveExitCode = hasProjects ? exitCode : 0;
+
   // A proposal over an unread tree would be a fabrication wearing a
   // proposal's name: every candidate edge would be ambiguous between "gone"
   // and "never seen". Refuse loudly — the same reasoning `drift`'s refusal
   // gives — rather than print a proposal and a warning that it may be lying.
-  if (propose && notAnalyzed.length > 0) {
+  // An unresolvable site is the same fabrication at site granularity (#595):
+  // the edge out of it may be missing, and a candidate built over a gap is
+  // still a guess. Use the shared verdict's counts rather than re-deriving.
+  if (propose && (verdict.notAnalyzed.length > 0 || verdict.blindSpotCount > 0)) {
     throw new Error(
-      `archkeep: discover --propose has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every candidate ` +
-        `would be ambiguous between "gone" and "never seen". Fix the unanalyzed files and ` +
-        `re-run.`,
+      `archkeep: discover --propose has incomplete coverage — ` +
+        [
+          verdict.notAnalyzed.length > 0
+            ? `${verdict.notAnalyzed.length} file${verdict.notAnalyzed.length === 1 ? "" : "s"} could not be analyzed`
+            : null,
+          verdict.blindSpotCount > 0
+            ? `${verdict.blindSpotCount} import site${verdict.blindSpotCount === 1 ? "" : "s"} could not be resolved`
+            : null,
+        ]
+          .filter(Boolean)
+          .join(", ") +
+        `, so every candidate would be ambiguous between "gone" and "never seen". ` +
+        `Fix the unresolved files and sites and re-run.`,
     );
   }
 
-  const complete = notAnalyzed.length === 0;
-  const status = complete ? "ok" : "no-verdict";
-  const exitCode = complete ? 0 : 3;
+  // The clauses the text face renders over an incomplete run, worded by the
+  // same function `verdictFor` joins into `decision.reason` — one wording,
+  // two renderings, and neither can drift from the other.
+  const coverageIncomplete = coverageIncompleteReasons({
+    unchecked: verdict.notAnalyzed.length,
+    blindSpots: verdict.blindSpotCount,
+    analyzed: analysis.analyzed,
+  });
 
   const coverage = {
-    complete,
+    complete: effectiveComplete,
     projects: observed.projects.length,
     analyzedFiles: analysis.analyzed,
     imports: analysis.imports.length,
-    notAnalyzed,
-    blindSpots: analysis.failures
-      .filter((failure) => !isWholeFileFailure(failure))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    notAnalyzed: verdict.notAnalyzed,
+    blindSpots: verdict.blindSpots,
     notes: [],
   };
 
@@ -176,14 +216,14 @@ export function discoverCommand(commandContext, { propose = false } = {}) {
   const envelope = jsonEnvelope({
     command: "discover",
     context,
-    status,
-    exitCode,
+    status: effectiveStatus,
+    exitCode: effectiveExitCode,
     coverage,
     result: { discovery, ...(proposal ? { proposal } : {}) },
   });
 
   return {
-    status,
+    status: effectiveStatus,
     discovery,
     proposal,
     coverage,
@@ -192,6 +232,7 @@ export function discoverCommand(commandContext, { propose = false } = {}) {
         discovery,
         proposal,
         coverage,
+        coverageIncomplete: hasProjects ? coverageIncomplete : undefined,
       }),
       json: renderJson(envelope),
     },

package/src/commands/drift.mjs

@@ -31,9 +31,11 @@
  *
  * - the intent file cannot be read or parsed (strict JSON, validated) → throw
  *   → exit 3;
- * - the observed side is incomplete (`notAnalyzed` non-empty) → exit 3, the
- *   same reasoning as `diff` — every "project missing" would be ambiguous
- *   between "gone" and "never seen";
+ * - the observed side is incomplete → the structured no-verdict refusal
+ *   (`./coverage-verdict.mjs`), exit 3, the same reasoning as `diff` — every
+ *   "project missing" would be ambiguous between "gone" and "never seen" —
+ *   but in the envelope, not on stderr: the same status/coverage contract
+ *   `graph`/`context` return over the same condition (#608);
  * - an Nx workspace has polyglot manifests but the plugin is not registered →
  *   exit 3, the same refusal `graph`/`diff` make;
  * - a boundary or row side matched no observed project → exit 3, the same
@@ -74,8 +76,9 @@
  * everywhere, never `localeCompare` — so two runs over an unchanged tree and
  * intent produce byte-identical text and JSON.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { blindSpotRows } from "../analysis/source-util.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { judgeIntent } from "../architecture-intent/judge.mjs";
@@ -290,11 +293,13 @@ function intentRows(intent) {
  *   row's `decisionRef`. `configError` carries a boundary-policy load failure
  *   the caller chose not to throw at the load site — rethrown here, unchanged,
  *   only if an intent row actually cites something.
- * @returns {Promise<{status: "ok", drift: object, coverage: object,
+ * @returns {Promise<{status: "ok"|"no-verdict", drift?: object, coverage: object,
  *   report: {text: string, json: string}}>}
- * @throws {Error} on every condition the header lists, all exit-3 class, plus
- *   a malformed ADR registry — the same loud refusal `provenance` makes for
- *   the identical read.
+ *   `status: "no-verdict"` carries no `drift` payload — the verdict was
+ *   withheld, and the envelope's `coverage` block is the whole answer (#608).
+ * @throws {Error} on every condition the header lists except the coverage one,
+ *   which returns instead of throwing, plus a malformed ADR registry — the
+ *   same loud refusal `provenance` makes for the identical read.
  */
 export async function driftCommand(commandContext, io = {}) {
   const { root, provider, marker, analysis } = commandContext;
@@ -302,16 +307,13 @@ export async function driftCommand(commandContext, io = {}) {
   refuseIncompleteGraph(commandContext);
 
   // A drift verdict cannot be established over a tree it could not fully read.
-  const notAnalyzed = analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: drift has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every "project missing" ` +
-        `would be ambiguous between "gone" and "never seen". Fix the unanalyzed files and re-run.`,
-    );
+  // The refusal is the structured one the graph family speaks (#608): the
+  // verdict is withheld in-band — status "no-verdict", exit 3, a `coverage`
+  // block naming every file and site the run could not judge — where a parser
+  // and `--output` can read it, not on stderr where only a human can.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "drift", commandContext, what: "judging drift" });
   }
 
   const intent = await (io.loadIntentOverride ?? loadIntent)(root, {
@@ -398,9 +400,7 @@ export async function driftCommand(commandContext, io = {}) {
     notAnalyzed: [],
     // Drift reads only the graph — provider failures are the same blind spots
     // every other command reports, and a blind spot never prevents a verdict.
-    blindSpots: analysis.failures
-      .filter((failure) => !isWholeFileFailure(failure))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    blindSpots: blindSpotRows(analysis.failures),
     // Coverage notes (e.g. an `optional: true` allowed row the team has not
     // built yet) ride here so "optional and absent" never reads as "never
     // checked".

package/src/commands/edge-constraints.mjs

@@ -42,6 +42,7 @@
  * enough that merging them would blur the layer boundary the AGENTS.md guards.
  */
 
+import { edgeEvolutionIdentity } from "../governance/evolution-event.mjs";
 import { renderMessage } from "../rules/messages.mjs";
 import { buildReachability } from "../rules/reachability.mjs";
 import {
@@ -212,7 +213,9 @@ export function declaredEdgeViolationsForCheck(graph, depConstraints) {
  * constraint table. The constraint table is the current one — it is what `check`
  * would judge from today, not what some past version judged from.
  *
- * @param {{addedEdges: object[], removedEdges: object[]}} diff From `computeDiff`.
+ * @param {{addedEdges: object[], removedEdges: object[],
+ *   changedProjects?: {name: string, changes: {field: string, baseline?: unknown,
+ *   head?: unknown}[]}[]}} diff From `computeDiff`.
  * @param {object} headNodes The head graph's `nodes` map (for tag lookups).
  * @param {object} headDependencies The head graph's `dependencies` map (for reachability).
  * @param {object[]} baselineProjects The baseline snapshot's project list (each
@@ -285,6 +288,49 @@ export function computeRuleImpact(
     }
   }
 
+  // Standing edges whose legality a tags-only change can flip (#600): the
+  // edge moved in neither direction, so the loops above never see it, but
+  // the tags its judgment reads did. An edge adjacent to a project whose
+  // tags changed is judged under BOTH sides' tags — violating under head
+  // where it was legal under baseline is an introduced violation, the
+  // inverse is a resolved one, and a violation under both is pre-existing
+  // (unchanged legality is `check`'s finding, not this diff's). Edges the
+  // loops above already judged are skipped by identity, so no edge is ever
+  // reported twice.
+  const tagChangedNames = new Set(
+    (diff.changedProjects ?? [])
+      .filter((project) => (project.changes ?? []).some((change) => change.field === "tags"))
+      .map((project) => project.name),
+  );
+  if (tagChangedNames.size > 0) {
+    const judged = new Set(
+      [...diff.addedEdges, ...diff.removedEdges].map((edge) => edgeEvolutionIdentity(edge)),
+    );
+    for (const edge of baselineDependencies) {
+      if (!(tagChangedNames.has(edge.source) || tagChangedNames.has(edge.target))) continue;
+      if (judged.has(edgeEvolutionIdentity(edge))) continue;
+      const headViolations = judgeEdge(
+        edge,
+        headNodes,
+        headDependencies,
+        depConstraints,
+        headReachability,
+      );
+      const baselineViolations = judgeEdge(
+        edge,
+        baselineNodes,
+        baselineDepsMap,
+        depConstraints,
+        baselineReachability,
+      );
+      if (headViolations.length > 0 && baselineViolations.length === 0) {
+        introduced.push(...headViolations);
+      } else if (baselineViolations.length > 0 && headViolations.length === 0) {
+        resolved.push(...baselineViolations);
+      }
+    }
+  }
+
   return { introduced, resolved };
 }