@ecoma-io/archkeep 0.21.0 → 0.22.0

package/src/commands/discover.mjs

@@ -40,7 +40,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 {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} 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";
@@ -131,6 +135,8 @@ export function discoverCommand(commandContext, { propose = false } = {}) {
     .filter(isWholeFileFailure)
     .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
 
+  const blindSpotCount = unresolvableLiteralCount(analysis.failures);
+
   const observed = buildObserved(commandContext);
 
   const proposal = propose ? evaluateDiscovery(observed) : null;
@@ -139,16 +145,32 @@ export function discoverCommand(commandContext, { propose = false } = {}) {
   // 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.
+  if (propose && (notAnalyzed.length > 0 || 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 — ` +
+        [
+          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 every candidate would be ambiguous between "gone" and "never seen". ` +
+        `Fix the unresolved files and sites and re-run.`,
     );
   }
 
-  const complete = notAnalyzed.length === 0;
+  // An unresolvable site was seen but never judged (#595): the snapshot's
+  // edge list under-represents the tree wherever that site would have drawn
+  // one, so `complete` cannot be claimed over it. It still reports — status
+  // no-verdict, exit 3 — naming the site in `coverage.blindSpots`.
+  const complete = notAnalyzed.length === 0 && blindSpotCount === 0;
   const status = complete ? "ok" : "no-verdict";
   const exitCode = complete ? 0 : 3;
 
@@ -158,9 +180,7 @@ export function discoverCommand(commandContext, { propose = false } = {}) {
     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/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 };
 }
 

package/src/commands/evaluation-primitives.mjs

@@ -9,6 +9,7 @@
  * @module
  */
 import { readAdrContext } from "./adr.mjs";
+import { edgeEvolutionIdentity } from "../governance/evolution-event.mjs";
 import { hasAuthority, resolveDecisionRef, stripAdrPrefix } from "../governance/adr-registry.mjs";
 import { isComboDepConstraint } from "../rules/tags.mjs";
 import { computeDecisionProvenance } from "../governance/provenance-graph.mjs";
@@ -16,9 +17,13 @@ import { resolveFileAttribution } from "./provenance.mjs";
 
 import {
   buildCompleteness,
+  buildEvidenceComplete,
   buildGovernanceCompleteness,
   evaluationStatus,
   EVALUATION_STATUS,
+  EVALUATION_CONTRACT_TYPES,
+  computeDomainCoverage,
+  REQUIRED_DOMAINS,
 } from "./completeness.mjs";
 import { computeImpact } from "./impact.mjs";
 import { computeImpactConstraints } from "./edge-constraints.mjs";
@@ -284,6 +289,116 @@ export function evaluateBoundaryImpact(graph, constraintImpact, targetProject) {
 // Canonical Architecture Evaluation
 // ---------------------------------------------------------------------------
 
+/**
+ * The provenance coverage of a decision set: the fraction of rows that
+ * resolved to a known record with authority.
+ *
+ * An ADR row counts when its record carries decision authority
+ * (`hasAuthority` — `accepted`/`active`); a fitness row counts when it
+ * resolved to an id the loaded policy binds (`resolution === "known"`).
+ * Refs that resolve to nothing are reported by `unresolvedDecisionRefs`
+ * and never become rows; a record without authority emits a row the gate
+ * fails on loudly rather than counting. One derivation, one home —
+ * `deriveEvidenceGates` and the scenario face both read it, so the two
+ * callers cannot disagree about what a covered decision is.
+ *
+ * @param {object[]|null|undefined} decisions Decision rows from
+ *   `buildDecisionImpact`.
+ * @returns {number} A ratio in [0, 1]; 0 when no decision binds an
+ *   affected row.
+ */
+export function decisionProvenanceCoverage(decisions) {
+  const rows = decisions ?? [];
+  if (rows.length === 0) return 0;
+  const covered = rows.filter((row) =>
+    row.kind === "adr" ? row.hasAuthority === true : row.resolution === "known",
+  ).length;
+  return covered / rows.length;
+}
+
+/**
+ * Derives evidence gates from evaluation outputs for the canonical evaluator.
+ *
+ * Each gate is computed from actual evaluation data rather than being
+ * caller-supplied. Gates not applicable to canonical evaluation
+ * (mutationCoverage, surfaceParity, baseIdentityValid) are set to 0/false
+ * and excluded via EVALUATION_CONTRACT_TYPES.CANONICAL.
+ *
+ * @param {object} evaluation The full evaluation result.
+ * @param {object} evaluation.completeness The completeness result.
+ * @param {object} evaluation.impact The structural impact.
+ * @param {object|null} evaluation.constraintImpact Constraint impact.
+ * @param {object|null} evaluation.decisionImpact Decision impact.
+ * @param {object} evaluation.boundaryImpact Boundary impact.
+ * @param {object} evaluation.findingsImpact Findings impact.
+ * @param {object} evaluation.debtImpact Debt impact.
+ * @param {object} evaluation.evolutionAlignment Evolution alignment.
+ * @returns {object} Evidence gate values for buildEvidenceComplete.
+ */
+export function deriveEvidenceGates(evaluation) {
+  const { completeness, constraintImpact, decisionImpact } = evaluation;
+
+  // domainCoverage: ratio of evaluated required domains
+  /** @type {{ [domain: string]: string }} */
+  const domainStatuses = {};
+  for (const domain of REQUIRED_DOMAINS) {
+    const dom = completeness.domains[domain];
+    domainStatuses[domain] = dom ? dom.status : EVALUATION_STATUS.NOT_EVALUATED;
+  }
+  const dc = computeDomainCoverage(domainStatuses);
+  const domainCoverage = dc.coverage;
+
+  // claimEvidenceCoverage: structural always produces claims with evidence.
+  // Constraint/decision claims exist when config is present.
+  const structuralClaimEvidence = 1; // structural always produces evidence
+  const constraintClaimEvidence = constraintImpact !== null ? 1 : 0;
+  const decisionClaimEvidence = decisionImpact !== null ? 1 : 0;
+  const totalClaims = 3; // structural + constraint + decision
+  const evidencedClaims = structuralClaimEvidence + constraintClaimEvidence + decisionClaimEvidence;
+  const claimEvidenceCoverage = totalClaims > 0 ? evidencedClaims / totalClaims : 0;
+
+  // causalCoverage: constraint consequences with complete causal chains
+  // When constraint impact is present, all constraint edges are traced.
+  // When absent, causal coverage is 0 (no constraints to trace).
+  const causalCoverage = constraintImpact !== null ? 1 : 0;
+
+  // provenanceCoverage: the fraction of decision rows that resolved to a
+  // known record with authority — derived from facts the rows carry, never
+  // from a property the row builder never wrote.
+  const provenanceCoverage = decisionProvenanceCoverage(decisionImpact?.decisions);
+
+  // mutationCoverage: not applicable for canonical evaluation
+  // surfaceParity: not applicable for canonical evaluation
+
+  // hiddenGapCount: NOT_EVALUATED domains without a note
+  let hiddenGapCount = 0;
+  for (const [, domain] of Object.entries(completeness.domains)) {
+    if (domain.status === EVALUATION_STATUS.NOT_EVALUATED && !domain.note) {
+      hiddenGapCount++;
+    }
+  }
+
+  // falseCompleteCount: detect when domains pass but evidence gates fail
+  // This is computed by buildCompleteness from the evidenceComplete contract.
+
+  // baseIdentityValid: not applicable for canonical evaluation
+
+  // deterministic: canonical evaluator is deterministic by construction
+  const deterministic = true;
+
+  return {
+    domainCoverage,
+    claimEvidenceCoverage,
+    causalCoverage,
+    provenanceCoverage,
+    mutationCoverage: 0,
+    surfaceParity: 0,
+    hiddenGapCount,
+    falseCompleteCount: 0,
+    baseIdentityValid: false,
+    deterministic,
+  };
+}
 /**
  * Evaluates the complete architecture state for a target project.
  *
@@ -435,6 +550,76 @@ export function evaluateArchitectureState({
     },
   });
 
+  // Derive evidence gates and build Evidence-Complete contract
+  const evaluationResult = {
+    completeness,
+    impact,
+    constraintImpact,
+    decisionImpact,
+    boundaryImpact,
+    findingsImpact,
+    debtImpact,
+    evolutionAlignment,
+  };
+  const evidenceGates = deriveEvidenceGates(evaluationResult);
+  const evidenceComplete = buildEvidenceComplete({
+    ...evidenceGates,
+    contractType: EVALUATION_CONTRACT_TYPES.CANONICAL,
+  });
+
+  // Rebuild completeness with evidenceComplete contract
+  const completenessWithEC = buildCompleteness({
+    structural: {
+      status: structuralStatus,
+      evaluated: true,
+      partial: false,
+      notEvaluated: false,
+      unsupported: false,
+      refused: false,
+      note: "",
+    },
+    constraint: {
+      status: constraintStatus,
+      evaluated: hasConfig && config.depConstraints !== undefined,
+      partial: false,
+      notEvaluated: !hasConfig || config.depConstraints === undefined,
+      unsupported: false,
+      refused: false,
+      note: "",
+    },
+    boundary: {
+      status: boundaryStatus,
+      evaluated: hasConfig,
+      partial: false,
+      notEvaluated: !hasConfig,
+      unsupported: false,
+      refused: false,
+      note: "",
+    },
+    decision: {
+      status: decisionStatus,
+      evaluated: hasConfig,
+      partial: false,
+      notEvaluated: !hasConfig,
+      unsupported: false,
+      refused: false,
+      note: "",
+    },
+    findings: governanceResult.findings,
+    debt: governanceResult.debt,
+    governance: governanceResult.domain,
+    evidence: {
+      status: evidenceStatus,
+      evaluated: evidenceEvaluated,
+      partial: false,
+      notEvaluated: false,
+      unsupported: false,
+      refused: false,
+      note: "",
+    },
+    evidenceComplete,
+  });
+
   return {
     project: projectName,
     impact,
@@ -444,8 +629,9 @@ export function evaluateArchitectureState({
     boundaryImpact,
     findingsImpact,
     debtImpact,
-    completeness,
+    completeness: completenessWithEC,
     affectedProjects,
+    evidenceComplete,
   };
 }
 
@@ -473,7 +659,13 @@ export function buildEvolutionAlignment(projectName, impact, constraintImpact, r
     for (const entry of constraintImpact) {
       // Collect edge identities for each affected boundary
       for (const edge of entry.edges) {
-        const edgeId = `${entry.project}>${edge.target}:${edge.type}`;
+        // The canonical spelling — imported, not restated, so this surface
+        // cannot drift from `EvolutionEvent.affected`'s vocabulary.
+        const edgeId = edgeEvolutionIdentity({
+          source: entry.project,
+          target: edge.target,
+          type: edge.type,
+        });
         if (!affectedBoundaries.includes(edgeId)) {
           affectedBoundaries.push(edgeId);
         }

package/src/commands/evolution.mjs

@@ -80,6 +80,7 @@ import { debtChangeDiff, debtFactId, driftFactOf } from "../governance/debt-ledg
 import { computeAffectedDecisions } from "../governance/decision-lineage.mjs";
 import {
   classifyEvolution,
+  edgeEvolutionIdentity,
   eventDedupeKey,
   eventId,
   EVOLUTION_EVENT_SCHEMA_VERSION,
@@ -939,23 +940,24 @@ function buildEvolutionSummary(comparisons) {
         comparisons.flatMap((c) => c.observed.projects.changed.map((p) => p.name ?? p)),
       ),
     },
+    // The identity string is the ONE spelling `edgeEvolutionIdentity` owns —
+    // the same spelling `affected.boundaries` and every stored event carry.
+    // An edge without a complete triple has no identity to name, so it is
+    // dropped from the union and counted into `unnamedEdges` rather than
+    // leaking an object serialization into a field of identity strings.
     edges: {
       added: unique(
         comparisons.flatMap((c) =>
-          c.observed.edges.added.map((e) =>
-            e.source && e.target && e.type
-              ? `${e.source}→${e.target}:${e.type}`
-              : JSON.stringify(e),
-          ),
+          c.observed.edges.added
+            .filter((e) => e.source && e.target && e.type)
+            .map((e) => edgeEvolutionIdentity(e)),
         ),
       ),
       removed: unique(
         comparisons.flatMap((c) =>
-          c.observed.edges.removed.map((e) =>
-            e.source && e.target && e.type
-              ? `${e.source}→${e.target}:${e.type}`
-              : JSON.stringify(e),
-          ),
+          c.observed.edges.removed
+            .filter((e) => e.source && e.target && e.type)
+            .map((e) => edgeEvolutionIdentity(e)),
         ),
       ),
     },
@@ -983,6 +985,21 @@ function buildEvolutionSummary(comparisons) {
   };
 
   const notes = unique(comparisons.flatMap((c) => c.notes ?? []));
+  const unnamedEdges = comparisons.reduce(
+    (count, c) =>
+      count +
+      [...c.observed.edges.added, ...c.observed.edges.removed].filter(
+        (e) => !(e.source && e.target && e.type),
+      ).length,
+    0,
+  );
+  if (unnamedEdges > 0) {
+    // The house shape for "we could not name it": a note naming the gap,
+    // never a silent drop dressed as a clean union.
+    notes.push(
+      `${unnamedEdges} changed edge(s) carry no complete identity and are not named in observed.edges`,
+    );
+  }
   return {
     transitions: comparisons.length,
     disposition,

package/src/commands/explain.mjs

@@ -79,7 +79,11 @@
  * was: the field, and its rendered lines, exist only when the comparison was
  * requested.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
 import { evaluate } from "../rules/index.mjs";
 import { findConstraintsFor } from "../rules/tags.mjs";
@@ -369,7 +373,13 @@ export function explainCommand(site, commandContext, config, options = {}) {
     .filter(isWholeFileFailure)
     .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
 
-  const complete = notAnalyzed.length === 0;
+  // An unresolvable site was seen but never judged (#595): the graph is
+  // missing whatever edge that site would have drawn, and rules that judge
+  // the whole graph (circularity, lazy loading) would answer over a gap. The
+  // explanation still reports — status no-verdict — naming the site in
+  // `coverage.blindSpots`, the same contract `graph`/`discover` run.
+  const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
+  const complete = notAnalyzed.length === 0 && blindSpotCount === 0;
   const status = complete ? "ok" : "no-verdict";
 
   // Find the import record at this site.
@@ -422,14 +432,7 @@ export function explainCommand(site, commandContext, config, options = {}) {
         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: blindSpotRows(commandContext.analysis.failures),
         notes: [],
       };
 
@@ -576,9 +579,7 @@ export function explainCommand(site, commandContext, config, options = {}) {
     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: blindSpotRows(commandContext.analysis.failures),
     notes: [],
   };
 

package/src/commands/fitness.mjs

@@ -45,10 +45,11 @@
  * sorted; JSON rides `canonicalizeJson`. Two runs over an unchanged tree and
  * policy produce byte-identical text and JSON.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { blindSpotRows } from "../analysis/source-util.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatFitnessSection } from "../report/text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { driftForCheck } from "./drift.mjs";
 import {
   evaluateFitness,
@@ -114,9 +115,13 @@ export function declaresFitness(config) {
  *
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {{config?: object|null}} [io] The loaded policy, injectable for tests.
- * @returns {Promise<{status: "ok"|"findings"|"no-verdict", fitness: object, coverage: object,
- *   report: {text: string, json: string}}>}
- * @throws {Error} on every condition the header lists, all exit-3 class.
+ * @returns {Promise<{status: "ok"|"findings"|"no-verdict", fitness?: object,
+ *   coverage: object, report: {text: string, json: string}}>}
+ *   `status: "no-verdict"` from the coverage refusal carries no `fitness`
+ *   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.
  */
 export async function fitnessCommand(commandContext, io = {}) {
   const { root, provider, marker, analysis } = commandContext;
@@ -129,18 +134,16 @@ export async function fitnessCommand(commandContext, io = {}) {
     );
   }
 
-  // A verdict over a tree it could not fully read is a guess. Same refusal
-  // `drift`/`graph`/`diff` make for the same condition.
-  const notAnalyzed = analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: fitness has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every coverage ` +
-        `and graph claim would be ambiguous between "clean" and "never seen". Fix the ` +
-        `unanalyzed files and re-run.`,
-    );
+  // A verdict over a tree it could not fully read is a guess. Refused through
+  // the one structured contract `./coverage-verdict.mjs` builds (#608) — this
+  // gate used to check whole-file failures only and then claim
+  // `coverage.complete: true` beside `blindSpots` that could carry an unjudged
+  // site, which the envelope law refuses as a programming error. The unified
+  // completeness returns the no-verdict envelope instead, for every axis the
+  // envelope law already withholds over.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "fitness", commandContext, what: "judging fitness" });
   }
 
   // `drift-free` judges the SAME verdict-shaped intent `check`'s fold builds —
@@ -192,9 +195,7 @@ export async function fitnessCommand(commandContext, io = {}) {
     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: [],
   };