@ecoma-io/archkeep 0.21.0 → 0.22.0

package/src/commands/change.mjs

@@ -71,16 +71,20 @@
  * change lives in `./change-intent.mjs`'s validation (`parseChangeIntent`),
  * the same loud lane as every other malformed declaration.
  *
- * Refusals (each a throw → exit 3 upstream): a manifest that fails shape or
- * reference validation, an unreadable/malformed/foreign-schema baseline,
- * incomplete baseline coverage, a provider mismatch, incomplete head
- * coverage, an unregistered-plugin graph over polyglot manifests, and a run
- * with no boundary law (constraints and the law fingerprint need one).
+ * Refusals: incomplete head coverage 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 manifest that fails shape or reference validation, an
+ * unreadable/malformed/foreign-schema baseline, incomplete baseline coverage,
+ * a provider mismatch, an unregistered-plugin graph over polyglot manifests,
+ * and a run with no boundary law (constraints and the law fingerprint need
+ * one).
  *
  * This module computes and returns; `../../cli.mjs`'s `runChange` owns argv,
  * output destination and the process exit code (`./README.md`).
  */
-import { classifyDelta } from "./delta-classify.mjs";
+import { classifyDelta, edgeEvolutionIdentity } from "./delta-classify.mjs";
 import { computeDiff } from "./diff.mjs";
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
 import {
@@ -91,10 +95,12 @@ import {
 } from "./change-intent.mjs";
 import {
   evidenceGraphToProjectGraph,
-  refuseUnjudgeableHead,
+  refusePluginGapHead,
   sourceProjectAttributor,
 } from "./delta.mjs";
 import { providerMismatch, readEvidenceSnapshot } from "./delta-snapshot.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
+import { blindSpotRows } from "../analysis/source-util.mjs";
 import { cyclicProjects } from "../governance/fitness-rules.mjs";
 import { fitnessVerdict } from "../governance/verdict.mjs";
 import { buildDecision } from "../report/evidence.mjs";
@@ -154,25 +160,16 @@ function violationFindingId(entry) {
   return `${entry.messageId}:${entry.sourceProject ?? "-"}:${entry.target}`;
 }
 
-/**
- * The identity string an observed edge carries into the event's `observed`
- * and `affected` — `(source, target, type)`, the triple `./diff.mjs`'s
- * `edgeIdentityKey` owns, spelled for a human reader (`>` separator, optional
- * type suffix). Two spellings of one triple never diverge because the triple
- * itself is the input.
- *
- * @param {{source: string, target: string, type?: string}} edge
- * @returns {string}
- */
-function edgeIdentityString(edge) {
-  return `${edge.source}>${edge.target}${edge.type === undefined || edge.type === "" ? "" : `:${edge.type}`}`;
-}
-
 /**
  * The structural-diff facts in the event's `observed` shape (design §1),
  * mapped from `computeDiff`'s output and the metadata comparison — the same
  * lists the reconciliation already consumed, never recomputed.
  *
+ * The edges' identity strings come from `edgeEvolutionIdentity`
+ * (`./delta-classify.mjs`) — the ONE spelling the evolution events'
+ * `observed.edges`/`affected.boundaries` use. A local spelling here would be
+ * a second definition of "same edge", and two definitions drift.
+ *
  * @param {{addedProjects: object[], removedProjects: object[],
  *   changedProjects: object[], addedEdges: object[], removedEdges: object[]}} structural
  * @param {{policyChanged: boolean|null, policyOneSided: boolean,
@@ -189,8 +186,8 @@ function observedFrom(structural, meta) {
     changed: structural.changedProjects.map((project) => project.name),
   };
   const edges = {
-    added: structural.addedEdges.map(edgeIdentityString),
-    removed: structural.removedEdges.map(edgeIdentityString),
+    added: structural.addedEdges.map(edgeEvolutionIdentity),
+    removed: structural.removedEdges.map(edgeEvolutionIdentity),
   };
   return {
     architectureChanged:
@@ -490,8 +487,14 @@ function judgeDeclaredConstraints(intent, io) {
  *   change event's `debt` diff judges the intent over this run's base and
  *   head graphs and would be untestable without it.
  * @returns {Promise<{status: "ok"|"findings"|"no-verdict",
- *   changeIntent: object, coverage: object, report: {text: string, json: string}}>}
- * @throws {Error} on every refusal the module header lists.
+ *   changeIntent?: object, coverage: object, report: {text: string, json: string}}>}
+ *   `status: "no-verdict"` from the coverage refusal (#608) carries no
+ *   `changeIntent` payload — the reconciliation was withheld, and the
+ *   envelope's `coverage` block plus its `decision.reason` are the whole
+ *   answer.
+ * @throws {Error} on every refusal the module header lists. Incomplete head
+ *   coverage returns the structured no-verdict envelope instead of throwing
+ *   (#608); the unregistered-plugin graph keeps its throw.
  */
 export async function changeCommand(
   baselinePath,
@@ -530,7 +533,23 @@ export async function changeCommand(
     );
   }
 
-  refuseUnjudgeableHead(commandContext, "reconcile a change intent");
+  // The plugin-gap refusal stays a throw; the coverage refusal returns the one
+  // structured envelope `./coverage-verdict.mjs` builds (#608) — status
+  // "no-verdict", exit 3, a `coverage` block naming every file and site the
+  // run could not judge — instead of the throw `refuseUnjudgeableHead` used to
+  // carry here. Reconciling a declaration over a half-read tree would answer
+  // "undeclared" about architecture the run never observed, and that refusal
+  // belongs in-band, where a parser and `--output` can read it.
+  refusePluginGapHead(commandContext, "reconcile a change intent");
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({
+      command: "change",
+      commandContext,
+      what: "reconciling a change intent",
+      decision: true,
+    });
+  }
 
   const intent = await (readIntent ? readIntent(intentPath) : readChangeIntent(intentPath));
 
@@ -718,7 +737,12 @@ export async function changeCommand(
     analyzedFiles: analysis.analyzed,
     imports: analysis.imports.length,
     notAnalyzed: [],
-    blindSpots: [],
+    // The positioned failures the run SAW — including the dynamic and external
+    // sites that never withhold a verdict. This used to be hardcoded `[]`
+    // (#609): a declared limit named nowhere is a disclosure gap, and
+    // `blindSpotRows` is the one mapping every other command's coverage block
+    // carries.
+    blindSpots: blindSpotRows(analysis.failures),
     notes,
   };
 
@@ -745,7 +769,14 @@ export async function changeCommand(
     reason: entry.reason,
   }));
   const evolution = classifyEvolution({
-    observed,
+    // The raw triples, not the mapped strings `observed` carries (that object
+    // is the event's stored record): `classifyEvolution` owns the identity
+    // spelling and takes the triples, so `affected.boundaries` is mapped
+    // inside it under the one spelling rather than trusted from the caller.
+    observed: {
+      ...observed,
+      edges: { added: structural.addedEdges, removed: structural.removedEdges },
+    },
     ...(classification === null
       ? {}
       : {

package/src/commands/check.mjs

@@ -12,7 +12,12 @@
 import { statSync } from "node:fs";
 import { join } from "node:path";
 
-import { fileFailure, isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  fileFailure,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { tsconfigPathsFacts } from "../analysis/typescript.mjs";
 import { stripTrailingSlashes } from "../path-util.mjs";
 import { suppressionCovers } from "../config.mjs";
@@ -188,7 +193,7 @@ function declaredEdgeManifest({ provider, graph }, sourceProject) {
  *   intentUnresolved: number, intentUnresolvedDecisionRefs: number, fitnessFail: number,
  *   fitnessUnknown: number, customRuleFail: number, customRuleUnknown: number,
  *   customRuleEvidence: {rule: string, bytes: Uint8Array}[], customRulesDeclared: boolean,
- *   analyzed: number, unchecked: number, waived?: number}>}
+ *   analyzed: number, unchecked: number, blindSpots: number, waived?: number}>}
  */
 export async function check(options, { cwd, readGraph, listFiles = listTrackedFiles }) {
   const commandContext = resolveCommandContext(
@@ -196,7 +201,7 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
     { readGraph, listFiles },
   );
   const { root, graph, workspace, tracked } = commandContext;
-  const { imports, exemptedFiles } = commandContext.analysis;
+  const { imports, exemptedFiles, unsupportedLanguageFiles } = commandContext.analysis;
   const failures = [...commandContext.analysis.failures];
   const analyzed = commandContext.analysis.analyzed;
 
@@ -622,6 +627,18 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
     failures.filter(isWholeFileFailure).map((failure) => failure.sourceFile),
   ).size;
 
+  // Sites the run saw but never judged (#595): the file was analyzed, this
+  // site was not, and a pass over it would claim a verdict the run does not
+  // hold. Counted beside `unchecked` from one classifier
+  // (`unresolvableLiteralCount`) so the exit, the report and the envelope all
+  // agree from one number. The two classes that withholds nothing are
+  // excluded from the count: the declared dynamic limit — a non-literal
+  // `import()` argument, unknowable in principle — and the external
+  // bare-package site, whose resolvability depends on an installed dependency
+  // tree a workspace legitimately may not have (`isDynamicSiteFailure` and
+  // `isExternalSiteFailure` in source-util.mjs own the class line).
+  const blindSpotCount = unresolvableLiteralCount(failures);
+
   // A row of the boundary law that covers nothing is a boundary that stopped
   // being enforced, and — unlike a missing `reason`, which only a human can
   // judge — it is machine-detectable. Two tables can be dead, and both are
@@ -838,8 +855,38 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
           },
         ]
       : []),
+    // Files a project owns that no analyzer claims (#601): skipped before
+    // reading, so they land in no failure list — without this row the run
+    // would present the judged surface as the whole story. Disclosure, not
+    // failure: the row names them and their extensions, and leaves
+    // `complete` to the surface that WAS judged. Sorted, because the row's
+    // bytes must not vary with `git ls-files`' order (E-F10).
+    ...(unsupportedLanguageFiles.length > 0
+      ? [{ kind: "unsupported-language", files: [...unsupportedLanguageFiles].sort() }]
+      : []),
   ];
 
+  // One verdict computation for both faces: the JSON envelope spreads it and
+  // the text report renders its `reasons` beside the headline — a second call
+  // here would let the two faces disagree about a run neither re-derives from
+  // the other (`../verdict.mjs`'s header owns that argument).
+  const verdict = verdictFor({
+    violations: violations.length,
+    declaredEdgeFindings,
+    goWorkDrift,
+    tsconfigPathsDead,
+    intentFindings,
+    intentUnresolved,
+    intentUnresolvedDecisionRefs: intentUnresolvedDecisionRefRows.length,
+    unchecked,
+    analyzed,
+    blindSpots: blindSpotCount,
+    fitnessFail,
+    fitnessUnknown,
+    customRuleFail,
+    customRuleUnknown,
+  });
+
   const report =
     options.format === "json"
       ? renderJson(
@@ -861,36 +908,20 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
             // `decision` — the four-state verb of the same counts — so the
             // envelope's `decision.verdict` and its `status` are built from
             // exactly one computation and can never disagree.
-            ...verdictFor({
-              violations: violations.length,
-              declaredEdgeFindings,
-              goWorkDrift,
-              tsconfigPathsDead,
-              intentFindings,
-              intentUnresolved,
-              intentUnresolvedDecisionRefs: intentUnresolvedDecisionRefRows.length,
-              unchecked,
-              fitnessFail,
-              fitnessUnknown,
-              customRuleFail,
-              customRuleUnknown,
-            }),
+            ...verdict,
             coverage: {
-              complete: unchecked === 0,
+              // Complete means the run judged everything in scope: no
+              // whole-file failure (unchecked), no unresolvable site (#595),
+              // and at least one file analyzed (#599 — a run that judged
+              // nothing has no verdict to claim).
+              complete: unchecked === 0 && blindSpotCount === 0 && analyzed > 0,
               projects: Object.keys(graph.nodes).length,
               analyzedFiles: analyzed,
               imports: imports.length,
               notAnalyzed: failures
                 .filter(isWholeFileFailure)
                 .map(({ sourceFile, reason }) => ({ file: sourceFile, reason })),
-              blindSpots: failures
-                .filter((failure) => !isWholeFileFailure(failure))
-                .map(({ sourceFile, line, column, reason }) => ({
-                  file: sourceFile,
-                  line,
-                  column,
-                  reason,
-                })),
+              blindSpots: blindSpotRows(failures),
               notes,
               coverageGaps,
             },
@@ -1020,6 +1051,10 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
           // inspected" fact does (`../report/text.mjs`'s `formatReport`).
           notes,
           coverageGaps,
+          // `formatReport` (text) renders these beside the headline; the SARIF
+          // face files the same facts as warning notifications. Both faces of
+          // one run name the same clauses, in the same order.
+          coverageIncomplete: verdict.reasons,
           // `formatReport` (text) reads this to annotate an unresolved
           // decisionRef inline; `formatSarif` files each one as a warning
           // notification. Both faces of one run name the same citations, in
@@ -1052,5 +1087,9 @@ export async function check(options, { cwd, readGraph, listFiles = listTrackedFi
     customRulesDeclared: customRules !== null,
     analyzed,
     unchecked,
+    // The site-level count `verdictFor` needs: `cli.mjs` passes this whole
+    // return through `verdictFor` for the process's exit code, so a count the
+    // envelope saw but the exit code did not would let the two disagree.
+    blindSpots: blindSpotCount,
   };
 }

package/src/commands/completeness.mjs

@@ -45,6 +45,72 @@ export const NOT_EVALUATED = EVALUATION_STATUS.NOT_EVALUATED;
 export const UNSUPPORTED = EVALUATION_STATUS.UNSUPPORTED;
 export const REFUSED = EVALUATION_STATUS.REFUSED;
 
+// ---------------------------------------------------------------------------
+// Evaluation contract types — which gates are required per evaluation type
+// ---------------------------------------------------------------------------
+
+/**
+ * The evaluation contract types that determine which Evidence-Complete gates
+ * are required for `overallComplete`.
+ *
+ * - `canonical`: Standard architecture evaluation (no mutations, no scenario).
+ *   Gates NOT required: mutationCoverage, surfaceParity, baseIdentityValid.
+ * - `scenario`: Hypothetical scenario evaluation. ALL gates required.
+ *
+ * @type {Readonly<{CANONICAL: string, SCENARIO: string}>}
+ */
+export const EVALUATION_CONTRACT_TYPES = Object.freeze({
+  CANONICAL: "canonical",
+  SCENARIO: "scenario",
+});
+
+/**
+ * Which Evidence-Complete gates are required for each contract type.
+ * A gate not listed here is still tracked and reported but does NOT block
+ * `overallComplete` — it is explicitly not applicable for that evaluation type.
+ *
+ * @type {Readonly<Object<string, ReadonlySet<string>>>}
+ */
+export const REQUIRED_GATES_FOR_CONTRACT = Object.freeze({
+  [EVALUATION_CONTRACT_TYPES.CANONICAL]: Object.freeze(
+    new Set([
+      "domainCoverage",
+      "claimEvidenceCoverage",
+      "causalCoverage",
+      "provenanceCoverage",
+      "hiddenGapCount",
+      "falseCompleteCount",
+      "deterministic",
+    ]),
+  ),
+  [EVALUATION_CONTRACT_TYPES.SCENARIO]: Object.freeze(
+    new Set([
+      "domainCoverage",
+      "claimEvidenceCoverage",
+      "causalCoverage",
+      "provenanceCoverage",
+      "mutationCoverage",
+      "surfaceParity",
+      "hiddenGapCount",
+      "falseCompleteCount",
+      "baseIdentityValid",
+      "deterministic",
+    ]),
+  ),
+});
+
+/**
+ * Returns true when the given gate key is required for the given contract type.
+ *
+ * @param {string} gateKey The gate key (e.g. "domainCoverage").
+ * @param {string} [contractType] The evaluation contract type.
+ *   Defaults to SCENARIO (most restrictive).
+ * @returns {boolean}
+ */
+export function isGateRequired(gateKey, contractType = EVALUATION_CONTRACT_TYPES.SCENARIO) {
+  const required = REQUIRED_GATES_FOR_CONTRACT[contractType];
+  return required ? required.has(gateKey) : true;
+}
 // ---------------------------------------------------------------------------
 // Evidence-Complete gate names — the canonical roster
 // ---------------------------------------------------------------------------
@@ -69,6 +135,7 @@ export const EVIDENCE_COMPLETE_GATES = Object.freeze([
 
 /**
  * @typedef {object} EvidenceCompleteContract
+ * @property {string} contractType The evaluation contract type (canonical | scenario).
  * @property {number} domainCoverage Ratio of evaluated required domains to required domains (0-1).
  * @property {number} claimEvidenceCoverage Ratio of claims with valid evidence to material claims (0-1).
  * @property {number} causalCoverage Ratio of consequences with complete causal chain to material consequences (0-1).
@@ -82,16 +149,16 @@ export const EVIDENCE_COMPLETE_GATES = Object.freeze([
  * @property {string} overallStatus Overall Evidence-Complete status: "complete" | "incomplete" | "not_evaluated".
  * @property {boolean} overallComplete True only when ALL required gates pass.
  * @property {object} gates Individual gate statuses, keyed by gate name.
- * @property {object} gates.domainCoverage Gate status.
- * @property {object} gates.claimEvidenceCoverage Gate status.
- * @property {object} gates.causalCoverage Gate status.
- * @property {object} gates.provenanceCoverage Gate status.
- * @property {object} gates.mutationCoverage Gate status.
- * @property {object} gates.surfaceParity Gate status.
- * @property {object} gates.hiddenGapCount Gate status.
- * @property {object} gates.falseCompleteCount Gate status.
- * @property {object} gates.baseIdentityValid Gate status.
- * @property {object} gates.deterministic Gate status.
+ * @property {object} gates.domainCoverage Gate status with {value, pass, required}.
+ * @property {object} gates.claimEvidenceCoverage Gate status with {value, pass, required}.
+ * @property {object} gates.causalCoverage Gate status with {value, pass, required}.
+ * @property {object} gates.provenanceCoverage Gate status with {value, pass, required}.
+ * @property {object} gates.mutationCoverage Gate status with {value, pass, required}.
+ * @property {object} gates.surfaceParity Gate status with {value, pass, required}.
+ * @property {object} gates.hiddenGapCount Gate status with {value, pass, required}.
+ * @property {object} gates.falseCompleteCount Gate status with {value, pass, required}.
+ * @property {object} gates.baseIdentityValid Gate status with {value, pass, required}.
+ * @property {object} gates.deterministic Gate status with {value, pass, required}.
  */
 
 // ---------------------------------------------------------------------------
@@ -306,8 +373,10 @@ export function buildCompleteness({
   const statuses = Object.values(domains).map((d) => d.status);
   const domainOverallComplete = statuses.every((s) => s === EVALUATION_STATUS.EVALUATED);
 
-  // If an Evidence-Complete contract is provided, enforce it as a gate
-  let ecComplete = true;
+  // If an Evidence-Complete contract is provided, enforce it as a gate.
+  // When no contract is provided, overallComplete MUST be false — the
+  // evaluation has not proven its evidence gates.
+  let ecComplete = false;
   let falseCompleteCount = 0;
   if (evidenceComplete) {
     ecComplete = evidenceComplete.overallComplete;
@@ -346,6 +415,10 @@ export function buildCompleteness({
 /**
  * Builds an Evidence-Complete contract from the individual gate values.
  *
+ * Only gates required for the given `contractType` are considered for
+ * `overallComplete`. Gates not required are still tracked and reported
+ * but do NOT block completeness.
+ *
  * @param {object} gates
  * @param {number} [gates.domainCoverage] Ratio (0-1).
  * @param {number} [gates.claimEvidenceCoverage] Ratio (0-1).
@@ -357,6 +430,8 @@ export function buildCompleteness({
  * @param {number} [gates.falseCompleteCount] Count (0 = pass).
  * @param {boolean} [gates.baseIdentityValid] Boolean (true = pass).
  * @param {boolean} [gates.deterministic] Boolean (true = pass).
+ * @param {string} [gates.contractType] Evaluation contract type for gate
+ *   requirements (defaults to SCENARIO, the most restrictive).
  * @returns {EvidenceCompleteContract}
  */
 export function buildEvidenceComplete({
@@ -370,8 +445,9 @@ export function buildEvidenceComplete({
   falseCompleteCount = -1,
   baseIdentityValid = false,
   deterministic = false,
+  contractType = EVALUATION_CONTRACT_TYPES.SCENARIO,
 } = {}) {
-  const gates = {
+  const rawGates = {
     domainCoverage: { value: domainCoverage, pass: domainCoverage === 1 },
     claimEvidenceCoverage: { value: claimEvidenceCoverage, pass: claimEvidenceCoverage === 1 },
     causalCoverage: { value: causalCoverage, pass: causalCoverage === 1 },
@@ -384,9 +460,21 @@ export function buildEvidenceComplete({
     deterministic: { value: deterministic, pass: deterministic === true },
   };
 
-  const allPass = Object.values(gates).every((g) => g.pass);
+  // Only required gates block overallComplete
+  const allRequiredPass = Object.keys(rawGates)
+    .filter((key) => isGateRequired(key, contractType))
+    .every((key) => rawGates[key].pass);
+  // Annotate each gate with whether it is required for this contract type
+  /** @type {any} */
+  const gates = Object.fromEntries(
+    Object.entries(rawGates).map(([key, gate]) => [
+      key,
+      { ...gate, required: isGateRequired(key, contractType) },
+    ]),
+  );
 
   return {
+    contractType,
     domainCoverage,
     claimEvidenceCoverage,
     causalCoverage,
@@ -397,8 +485,8 @@ export function buildEvidenceComplete({
     falseCompleteCount,
     baseIdentityValid,
     deterministic,
-    overallStatus: allPass ? "complete" : "incomplete",
-    overallComplete: allPass,
+    overallStatus: allRequiredPass ? "complete" : "incomplete",
+    overallComplete: allRequiredPass,
     gates,
   };
 }
@@ -414,16 +502,22 @@ export function buildEvidenceComplete({
 export function assertEvidenceComplete(ec) {
   if (ec.overallComplete) return;
 
+  const contractType = ec.contractType || EVALUATION_CONTRACT_TYPES.SCENARIO;
   const failures = [];
   for (const gate of EVIDENCE_COMPLETE_GATES) {
     const g = ec.gates[gate.key];
+    // Skip non-required gates for this contract type
+    if (g.required === false) continue;
     if (!g.pass) {
       failures.push(`${gate.label}: ${JSON.stringify(g.value)} (expected pass)`);
     }
   }
 
+  if (failures.length === 0) return;
+
   throw new Error(
     `Evidence-Complete contract not satisfied.\n` +
+      `  Contract type: ${contractType}\n` +
       `  Overall: ${ec.overallStatus}\n` +
       `  Failed gates:\n    ${failures.join("\n    ")}`,
   );
@@ -571,15 +665,28 @@ export function buildScenarioCompleteness({
     evidenceComplete,
   });
 
-  // Recompute overall with scenario domains included
+  // Recompute overall: base domains + EC gate + scenario domains.
+  // baseResult.overallComplete already includes the evidenceComplete gate,
+  // so reusing it prevents the silent-complete defect.
+  const overallComplete =
+    baseResult.overallComplete &&
+    changesDomain.status === EVALUATION_STATUS.EVALUATED &&
+    baseDomain.status === EVALUATION_STATUS.EVALUATED &&
+    mutationDomain.status === EVALUATION_STATUS.EVALUATED;
   const allStatuses = [
     ...Object.values(baseResult.domains).map((d) => d.status),
     changesDomain.status,
     baseDomain.status,
     mutationDomain.status,
   ];
-  const overallComplete = allStatuses.every((s) => s === EVALUATION_STATUS.EVALUATED);
-  const overallStatus = worstStatus(...allStatuses);
+  // Include EC gate status in overall status: when evidenceComplete is
+  // provided and fails, overall status must reflect that.
+  const ecStatus = evidenceComplete
+    ? evidenceComplete.overallComplete
+      ? EVALUATION_STATUS.EVALUATED
+      : EVALUATION_STATUS.NOT_EVALUATED
+    : EVALUATION_STATUS.NOT_EVALUATED;
+  const overallStatus = worstStatus(...allStatuses, ecStatus);
 
   return {
     domains: baseResult.domains,

package/src/commands/context-command.mjs

@@ -32,7 +32,11 @@
  * than explaining constraints from a graph whose edges silently under-represent
  * the real architecture.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
 import { judgeEdge } from "./edge-constraints.mjs";
 import { findConstraintsFor } from "../rules/tags.mjs";
@@ -150,7 +154,13 @@ export function contextCommand(projectName, commandContext, config) {
     .filter(isWholeFileFailure)
     .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
 
-  const complete = notAnalyzed.length === 0;
+  // The same completeness `check` claims (#595, #599): unjudged sites and
+  // a zero-analyzed run defeat it here exactly as they do there, so a
+  // context report cannot look complete over a tree the run could not
+  // fully read.
+  const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
+  const complete =
+    notAnalyzed.length === 0 && blindSpotCount === 0 && commandContext.analysis.analyzed > 0;
   const status = complete ? "ok" : "no-verdict";
   const exitCode = complete ? 0 : 3;
 
@@ -160,9 +170,7 @@ export function contextCommand(projectName, commandContext, config) {
     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: [
       "per-edge violations cover only depConstraints (3 of 15 violation types). " +
         "A dependency with no violations here may still violate npm-ban, circular-dependency, " +

package/src/commands/context.mjs

@@ -214,11 +214,14 @@ export const WORKSPACE_MARKERS = [
  *   `createWorkspace` returns.
  * @property {string[]} tracked Every tracked file, from `listFiles(root)`.
  * @property {{imports: object[], failures: object[], analyzed: number,
- *   analyzedFiles: string[], exemptedFiles: string[]}} analysis The
+ *   analyzedFiles: string[], exemptedFiles: string[],
+ *   unsupportedLanguageFiles: string[]}} analysis The
  *   whole-tree-then-scoped (native) or scoped-then-analyzed (nx/moon) result —
  *   see the branches below for why the order is not the same on all three.
  *   `exemptedFiles` is always `[]` on nx/moon: `coverage.exempt` is a
- *   native-only `archkeep.json` key.
+ *   native-only `archkeep.json` key. `unsupportedLanguageFiles` is scoped to
+ *   the selected files on every branch (#601): a gap row names only files the
+ *   selected scope could have judged.
  * @property {{boundaryConfig: string|object, tsConfig: object|undefined,
  *   boundaryConfigDeclared: boolean, profiles?: string, inline?: boolean}} options
  *   What this workspace names its boundary law, its shared tsconfig, and —
@@ -549,6 +552,7 @@ export function resolveCommandContext(
   let failures;
   let analyzed;
   let analyzedFiles;
+  let unsupportedLanguageFiles;
   let pluginGap;
   let unownedGap;
   let unclaimedGap;
@@ -664,6 +668,12 @@ export function resolveCommandContext(
       ...jvmIndexFailures(workspace),
     ]);
     analyzedFiles = wholeTreeAnalysis.analyzedFiles.filter((file) => selectedFiles.has(file));
+    // Scoped exactly like `analyzedFiles` above (#601): a gap row must name
+    // only files the selected scope could have judged, and leaving this
+    // undefined here would crash `check`'s gap assembly instead of reporting.
+    unsupportedLanguageFiles = wholeTreeAnalysis.unsupportedLanguageFiles.filter((file) =>
+      selectedFiles.has(file),
+    );
     analyzed = analyzedFiles.length;
     // Unaffected by `paths`: an exempted file is by definition unowned by any
     // project, so it was never a candidate for `owned`/`selected` in the
@@ -787,6 +797,13 @@ export function resolveCommandContext(
     ]);
     unclaimedGap = { files: unclaimedFiles };
     analyzedFiles = wholeTreeAnalysis.analyzedFiles.filter((file) => selectedFiles.has(file));
+    // Scoped exactly like the native branch's own filter above (#601): a gap
+    // row must name only files the selected scope could have judged, and
+    // leaving this undefined here would crash `check`'s gap assembly instead
+    // of reporting.
+    unsupportedLanguageFiles = wholeTreeAnalysis.unsupportedLanguageFiles.filter((file) =>
+      selectedFiles.has(file),
+    );
     analyzed = analyzedFiles.length;
     // `coverage.exempt` is a native-only key (`../providers/native/coverage.mjs`'s
     // header: "Nx has no equivalent question") — Moon carries no such list.
@@ -835,7 +852,10 @@ export function resolveCommandContext(
       paths,
       { root, cwd, tracked },
     );
-    ({ imports, failures, analyzed, analyzedFiles } = analyzeWorkspace(workspace, selected));
+    ({ imports, failures, analyzed, analyzedFiles, unsupportedLanguageFiles } = analyzeWorkspace(
+      workspace,
+      selected,
+    ));
     // Unclaimed analyzable files — `unclaimedFileFailures` above — join
     // unconditionally, the same workspace-wide posture native's own
     // `discovered.failures` has, so a scoped `check <path>` cannot hide an
@@ -876,7 +896,14 @@ export function resolveCommandContext(
     graph,
     workspace,
     tracked,
-    analysis: { imports, failures, analyzed, analyzedFiles, exemptedFiles },
+    analysis: {
+      imports,
+      failures,
+      analyzed,
+      analyzedFiles,
+      exemptedFiles,
+      unsupportedLanguageFiles,
+    },
     options,
     pluginGap,
     unownedGap,