@ecoma-io/archkeep 0.21.0 → 0.22.0

package/src/commands/graph.mjs

@@ -29,7 +29,11 @@
  */
 import { createHash } from "node:crypto";
 
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { canonicalizeJson } from "../canonical.mjs";
 import { DEFAULT_WORKSPACE_LAYOUT } from "../rules/specifiers.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
@@ -222,7 +226,14 @@ export function graphCommand(commandContext, { config = null } = {}) {
     .filter(isWholeFileFailure)
     .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
 
-  const complete = notAnalyzed.length === 0;
+  // An unresolvable import site was seen but never judged (#595): the edges
+  // out of it may be missing from this snapshot, so the snapshot must not
+  // claim `complete` over it. It still reports — status no-verdict, exit 3 —
+  // naming the site in `coverage.blindSpots`, the same contract `check` runs.
+  const blindSpots = blindSpotRows(commandContext.analysis.failures);
+  const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
+
+  const complete = notAnalyzed.length === 0 && blindSpotCount === 0;
   const status = complete ? "ok" : "no-verdict";
   const exitCode = complete ? 0 : 3;
 
@@ -245,9 +256,7 @@ export function graphCommand(commandContext, { config = null } = {}) {
     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,
     notes: [],
   };
 

package/src/commands/health.mjs

@@ -43,7 +43,11 @@
  * It does not print, and it does not decide the process's exit code —
  * `../../cli.mjs` owns those (`./README.md`).
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatHealthReport } from "../report/health-text.mjs";
@@ -108,7 +112,12 @@ export function healthCommand(commandContext, io = {}) {
   const edges = buildDependencies(graph.dependencies);
 
   // The run's coverage facts, the same shape every command's envelope carries.
-  const fileComplete = analysis.failures.filter(isWholeFileFailure).length === 0;
+  // An unresolvable site is a fact the run saw but never judged (#595) —
+  // metrics measured over it would read precision the run does not have,
+  // so it defeats file completeness the way a whole-file failure does.
+  const fileComplete =
+    analysis.failures.filter(isWholeFileFailure).length === 0 &&
+    unresolvableLiteralCount(analysis.failures) === 0;
   // The graph is complete only when the files are AND the graph actually sees
   // every polyglot edge — an Nx workspace with an unregistered plugin carries
   // a graph with no Go/Rust/Python edges, which `graph`/`impact` refuse and
@@ -123,9 +132,7 @@ export function healthCommand(commandContext, io = {}) {
     notAnalyzed: analysis.failures
       .filter(isWholeFileFailure)
       .map(({ sourceFile, reason }) => ({ file: sourceFile, reason })),
-    blindSpots: analysis.failures
-      .filter((f) => !isWholeFileFailure(f))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    blindSpots: blindSpotRows(analysis.failures),
     notes: graphComplete
       ? []
       : [

package/src/commands/history.mjs

@@ -74,12 +74,16 @@ import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { containmentViolation } from "../containment.mjs";
 import { classifyEvolution } from "../governance/evolution-event.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatHistoryReport } from "../report/history-text.mjs";
-import { computeDiff, edgeIdentityKey, parseBaseline } from "./diff.mjs";
+import { computeDiff, parseBaseline } from "./diff.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
@@ -397,8 +401,12 @@ export function classifyTransition(from, to) {
         changed: diff.changedProjects.map((project) => project.name),
       },
       edges: {
-        added: diff.addedEdges.map(edgeIdentityKey),
-        removed: diff.removedEdges.map(edgeIdentityKey),
+        // The raw triples — `classifyEvolution` maps them through its own
+        // identity spelling (`edgeEvolutionIdentity`), so `affected.boundaries`
+        // carries the canonical strings every other event surface uses, not
+        // this module's diff-internal key spelling.
+        added: diff.addedEdges,
+        removed: diff.removedEdges,
       },
       policyChanged: meta.policyChanged,
       policyOneSided: meta.policyOneSided,
@@ -554,10 +562,23 @@ export function historyCommand(
     const notAnalyzed = commandContext.analysis.failures
       .filter(isWholeFileFailure)
       .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-    if (notAnalyzed.length > 0) {
+
+    const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
+    if (notAnalyzed.length > 0 || blindSpotCount > 0) {
       throw new Error(
-        `archkeep: the head graph has incomplete coverage — ${notAnalyzed.length} file` +
-          `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so a captured snapshot ` +
+        `archkeep: the head graph 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 
+a captured snapshot ` +
           `would under-represent the real architecture. Fix the unanalyzed files and re-run.`,
       );
     }
@@ -608,14 +629,7 @@ export function historyCommand(
           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: [],
         },
         result: { ...head, policy: headPolicy ?? undefined },

package/src/commands/impact.mjs

@@ -35,9 +35,9 @@
  * under project roots, `impact` refuses loudly rather than returning a result
  * whose dependents silently under-represent the real architecture.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
 import { computeImpactConstraints } from "./edge-constraints.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatImpactReport } from "../report/impact-text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
@@ -123,11 +123,14 @@ export function computeImpact(projectName, graph) {
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {object} [config] The loaded boundary config. When provided,
  *   constraint context and violations for each dependent edge are computed.
- * @returns {{status: "ok"|"no-verdict", impact: object, coverage: object,
+ * @returns {{status: "ok"|"no-verdict", impact?: object, coverage: object,
  *   report: {text: string, json: string}}}
+ *   `status: "no-verdict"` carries no `impact` payload — the verdict was
+ *   withheld, and the envelope's `coverage` block is the whole answer (#608).
  * @throws {Error} when an Nx workspace has polyglot manifests but the plugin
- *   is not registered, or when the named project does not exist in the graph,
- *   or when the graph has incomplete coverage.
+ *   is not registered, or when the named project does not exist in the graph.
+ *   Incomplete coverage returns the structured no-verdict envelope instead of
+ *   throwing (#608).
  */
 export function impactCommand(projectName, commandContext, config = null) {
   const { root, provider, marker, graph, pluginGap } = commandContext;
@@ -150,22 +153,18 @@ export function impactCommand(projectName, commandContext, config = null) {
   // project before the run invests in anything else.
   const impact = computeImpact(projectName, graph);
 
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: the graph has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so the impact set may ` +
-        `under-represent the real architecture. Fix the unanalyzed files and re-run.`,
-    );
+  // The impact set is a claim about the tree the run read, refused through the
+  // one structured contract `./coverage-verdict.mjs` builds (#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: "impact", commandContext, what: "computing impact" });
   }
-  const blindSpots = commandContext.analysis.failures
-    .filter((f) => !isWholeFileFailure(f))
-    .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason }));
+  const blindSpots = completeness.blindSpots;
 
-  const complete = true; // whole-file failures already threw above
+  const complete = true; // the incompleteness cases all returned above
   const status = "ok";
   const exitCode = 0;
 

package/src/commands/plan-context-command.mjs

@@ -64,7 +64,11 @@ import { statSync } from "node:fs";
 import { join } from "node:path";
 
 import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { tsconfigPathsFacts } from "../analysis/typescript.mjs";
 import { compareGoWork, parseGoWorkUse } from "../go-work.mjs";
 import { judgeTsconfigPaths } from "../tsconfig-paths.mjs";
@@ -497,7 +501,10 @@ export async function planContextCommand(
         (a.messageId < b.messageId ? -1 : a.messageId > b.messageId ? 1 : 0),
     );
 
-  const complete = notAnalyzed.length === 0;
+  // An unresolvable literal site is work the run saw but never judged
+  // (#595, narrowed): a plan over it would present edges the run does not
+  // hold, so it defeats completeness the way a whole-file failure does.
+  const complete = notAnalyzed.length === 0 && unresolvableLiteralCount(failures) === 0;
   const status = complete ? "ok" : "no-verdict";
   const exitCode = complete ? 0 : 3;
 
@@ -525,9 +532,7 @@ export async function planContextCommand(
     analyzedFiles: wholeTree.analyzed,
     imports: wholeTree.imports.length,
     notAnalyzed,
-    blindSpots: failures
-      .filter((failure) => !isWholeFileFailure(failure))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    blindSpots: blindSpotRows(failures),
     // Intent's own coverage notes ride the same seam `check` threads them on
     // (today only an `"optional": true` allowed row whose statement is absent),
     // so the plan's text and JSON reports read the same notes `check` does.

package/src/commands/reconcile.mjs

@@ -43,9 +43,10 @@
  * comparison (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 { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { resolveProvenance } from "./provenance.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { judgeIntent } from "../architecture-intent/judge.mjs";
 import { computeIntentFingerprint } from "../architecture-intent/intent-fingerprint.mjs";
 import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
@@ -84,9 +85,12 @@ function intentRows(intent) {
  * @param {{loadIntentOverride?: (root: string) => Promise<object>}} [io]
  *   Injectable intent loader for tests.
  * @param {{propose?: boolean}} [options] `--propose` adds the ranked candidate list.
- * @returns {Promise<{status: "ok", reconcile: object, coverage: object,
+ * @returns {Promise<{status: "ok"|"no-verdict", reconcile?: object, coverage: object,
  *   report: {text: string, json: string}}>}
- * @throws {Error} on every condition the header lists, all exit-3 class.
+ *   `status: "no-verdict"` carries no `reconcile` 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 reconcileCommand(commandContext, io = {}, options = {}) {
   const { root, provider, marker, analysis } = commandContext;
@@ -94,17 +98,12 @@ export async function reconcileCommand(commandContext, io = {}, options = {}) {
   refuseIncompleteGraph(commandContext);
 
   // A reconcile verdict cannot be established over a tree it could not fully
-  // read — the same fail-closed condition `drift` enforces.
-  const notAnalyzed = analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: reconcile has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every "absent" score ` +
-        `would be ambiguous between "gone" and "never seen". Fix the unanalyzed files and re-run.`,
-    );
+  // read — the same fail-closed condition `drift` enforces, refused through
+  // the same structured envelope `./coverage-verdict.mjs` builds (#608): the
+  // verdict is withheld in-band, where a parser and `--output` can read it.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "reconcile", commandContext, what: "reconciling" });
   }
 
   const intent = await (io.loadIntentOverride ?? loadIntent)(root, {
@@ -146,9 +145,7 @@ export async function reconcileCommand(commandContext, io = {}, options = {}) {
     // Reconcile 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/scenario-evaluation.mjs

@@ -33,12 +33,21 @@
  */
 import { computeImpact } from "./impact.mjs";
 import { computeImpactConstraints } from "./edge-constraints.mjs";
-import { buildDecisionImpact, buildEvolutionAlignment } from "./evaluation-primitives.mjs";
+import {
+  buildDecisionImpact,
+  buildEvolutionAlignment,
+  decisionProvenanceCoverage,
+} from "./evaluation-primitives.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import {
-  buildScenarioCompleteness,
   buildGovernanceCompleteness,
+  buildScenarioCompleteness,
+  buildEvidenceComplete,
+  createDomain,
+  EVALUATED,
+  NOT_EVALUATED,
   evaluationStatus,
+  EVALUATION_CONTRACT_TYPES,
 } from "./completeness.mjs";
 
 // ---------------------------------------------------------------------------
@@ -105,8 +114,8 @@ export const SCENARIO_CHANGE_TYPES = Object.freeze(["dependency_added", "depende
  * @property {string} evidenceChain.scenarioState The state after applying changes ("scenario").
  * @property {object} evidenceChain.delta The computed differences.
  * @property {object} [governanceImpact] Governance re-evaluation results.
- * @property {boolean} governanceImpact.findingsReEvaluated Whether findings were re-evaluated.
- * @property {boolean} governanceImpact.debtReEvaluated Whether debt was re-evaluated.
+ * @property {boolean} governanceImpact.findingsFiltered Whether precomputed findings were filtered into the scenario state.
+ * @property {boolean} governanceImpact.debtFiltered Whether precomputed debt was filtered into the scenario state.
  * @property {boolean} governanceImpact.governanceComplete Whether all governance data was provided.
  * @property {number} governanceImpact.scenarioFindingsCount Number of findings in the scenario state.
  * @property {number} governanceImpact.scenarioDebtCount Number of debt entries in the scenario state.
@@ -587,17 +596,19 @@ export function evaluateScenario(
   // hypothetical graph) is NOT governance re-evaluation. True re-evaluation
   // would run the full check pipeline against the hypothetical graph.
   // When we only filter, governance is NOT_EVALUATED.
-  const findingsReEvaluated = availableFindings !== null;
-  const debtReEvaluated = availableDebt !== null;
+  const findingsFiltered = availableFindings !== null;
+  const debtFiltered = availableDebt !== null;
 
-  // Mark governance as NOT_EVALUATED when not truly re-evaluated
+  // Filtering is NOT re-evaluation (the header above), so the status is
+  // NOT_EVALUATED on both paths — no re-evaluation pipeline exists to pass.
+  // Telling a consumer "evaluated" for a filter is the mislabel this refuses.
   const findingsStatus = evaluationStatus({
-    evaluated: false, // filtering is NOT evaluation
-    notEvaluated: !findingsReEvaluated,
+    evaluated: false,
+    notEvaluated: true,
   });
   const debtStatus = evaluationStatus({
-    evaluated: false, // filtering is NOT evaluation
-    notEvaluated: !debtReEvaluated,
+    evaluated: false,
+    notEvaluated: true,
   });
 
   // Build governance completeness
@@ -614,12 +625,78 @@ export function evaluateScenario(
   const refusedCount = refused.length;
   const mutationCoverageComplete = totalChanges === appliedCount && refusedCount === 0;
 
-  // Build overall scenario completeness
+  // Build the scenario's domain statuses FIRST — the Evidence-Complete
+  // contract below derives its hidden-gap gate from them, so a domain that
+  // is NOT_EVALUATED without a note flips that gate, and a domain that
+  // skips with a stated reason does not.
+  //   structural — always evaluated (scenario builds a complete graph).
+  //   constraint, boundary, decision — require a boundary config; decision
+  //     follows the config exactly as the canonical face reads it, because
+  //     the scenario runs decision impact (buildDecisionImpact above) when
+  //     one is present. The condition this replaces, `config.decisionRefs`,
+  //     named a field no workspace can declare — it held the decision domain
+  //     at NOT_EVALUATED forever, a permanent hidden gap on every configured
+  //     workspace.
+  //   findings, debt — never re-evaluated in a scenario; the notes say so,
+  //     which is what keeps them disclosed and out of the hidden-gap count.
+  //   evidence — always evaluated (we build the EC contract).
+  const hasConfig = config !== null;
+  const configGapNote =
+    "No boundary config — constraint, boundary and decision rules not evaluated";
+  const configGated = () =>
+    hasConfig ? createDomain(EVALUATED) : createDomain(NOT_EVALUATED, configGapNote);
+  const scenarioDomains = {
+    structural: createDomain(EVALUATED),
+    constraint: configGated(),
+    boundary: configGated(),
+    decision: configGated(),
+    findings:
+      governanceCompleteness.findings.status === NOT_EVALUATED
+        ? createDomain(NOT_EVALUATED, "Findings not re-evaluated in scenario")
+        : governanceCompleteness.findings,
+    debt:
+      governanceCompleteness.debt.status === NOT_EVALUATED
+        ? createDomain(NOT_EVALUATED, "Debt not re-evaluated in scenario")
+        : governanceCompleteness.debt,
+    evidence: createDomain(EVALUATED),
+  };
+
+  // Hidden gaps: NOT_EVALUATED domains without a stated reason — the same
+  // derivation `deriveEvidenceGates` runs for the canonical face, so neither
+  // face can pass the gate on a literal while the other fails on facts.
+  let scenarioHiddenGapCount = 0;
+  for (const domainStatus of Object.values(scenarioDomains)) {
+    if (domainStatus.status === NOT_EVALUATED && !domainStatus.note) {
+      scenarioHiddenGapCount++;
+    }
+  }
+
+  // Derive evidence gates for scenario evaluation and build Evidence-Complete contract.
+  // Scenario mutation is deterministic: same inputs → same outputs (pure graph clone + apply).
+  // surfaceParity: the scenario applied all requested changes (refused===0), so the
+  // hypothetical surface is internally consistent — no surface drift from the plan.
+  const surfaceParity = refusedCount === 0 ? 1 : 0;
+
+  const evidenceComplete = buildEvidenceComplete({
+    domainCoverage: currentDecisionImpact !== null ? 1 : 0,
+    claimEvidenceCoverage: config !== null ? 1 : 0,
+    causalCoverage: currentConstraintImpact !== null ? 1 : 0,
+    provenanceCoverage: decisionProvenanceCoverage(currentDecisionImpact?.decisions),
+    mutationCoverage: mutationCoverageComplete ? 1 : 0,
+    surfaceParity,
+    hiddenGapCount: scenarioHiddenGapCount,
+    falseCompleteCount: 0,
+    baseIdentityValid: base.identityVerified,
+    deterministic: true,
+    contractType: EVALUATION_CONTRACT_TYPES.SCENARIO,
+  });
   const scenarioCompleteness = buildScenarioCompleteness({
     changesComplete: mutationCoverageComplete,
     baseIdentityVerified: base.identityVerified,
     mutationCoverageComplete,
     governance: governanceCompleteness,
+    evidenceComplete,
+    domains: scenarioDomains,
   });
 
   return {
@@ -655,9 +732,9 @@ export function evaluateScenario(
       ...(scenarioDebt !== null ? { debt: scenarioDebt } : {}),
     },
     governanceImpact: {
-      findingsReEvaluated,
-      debtReEvaluated,
-      governanceComplete: false, // filtering is NOT evaluation
+      findingsFiltered,
+      debtFiltered,
+      governanceComplete: false,
       scenarioFindingsCount: scenarioFindings?.length ?? 0,
       scenarioDebtCount: scenarioDebt?.length ?? 0,
       findingsStatus,
@@ -665,7 +742,7 @@ export function evaluateScenario(
     },
     delta,
     completeness: scenarioCompleteness,
-    complete: mutationCoverageComplete,
+    complete: scenarioCompleteness.overallComplete,
     notes,
   };
 }

package/src/commands/scenario.mjs

@@ -11,7 +11,7 @@
  */
 import { resolveProvenance } from "./provenance.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { evaluateScenario, parseScenarioInput } from "./scenario-evaluation.mjs";
 export { parseScenarioInput } from "./scenario-evaluation.mjs";
 
@@ -23,7 +23,10 @@ export { parseScenarioInput } from "./scenario-evaluation.mjs";
  * @param {string} scenarioJson The scenario description as JSON.
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {object} [config] The loaded boundary config.
- * @returns {{status: string, scenario: object, coverage: object, report: {text: string, json: string}}}
+ * @returns {{status: "ok"|"no-verdict", scenario?: object, coverage: object,
+ *   report: {text: string, json: string}}} `scenario` is absent under
+ *   `status: "no-verdict"` — the coverage refusal (#608) withholds the
+ *   evaluation, and the envelope's `coverage` block is the whole answer.
  */
 export function scenarioCommand(projectName, scenarioJson, commandContext, config = null) {
   const { root, provider, marker, graph, pluginGap } = commandContext;
@@ -44,17 +47,12 @@ export function scenarioCommand(projectName, scenarioJson, commandContext, confi
   // Parse the scenario input
   const scenarioInput = parseScenarioInput(scenarioJson);
 
-  // Check coverage
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: the graph has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so the scenario may ` +
-        `under-represent the real architecture. Fix the unanalyzed files and re-run.`,
-    );
+  // Check coverage — refused through the one structured contract
+  // `./coverage-verdict.mjs` builds (#608): the evaluation is withheld
+  // in-band, where a parser and `--output` can read it.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "scenario", commandContext, what: "evaluating a scenario" });
   }
 
   // Evaluate
@@ -66,9 +64,7 @@ export function scenarioCommand(projectName, scenarioJson, commandContext, confi
     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: [
       "scenario evaluation is virtual and not authoritative — run `check` for the real verdict",
       "per-edge verdicts cover only depConstraints (3 of 15 violation types)",
@@ -103,7 +99,7 @@ export function scenarioCommand(projectName, scenarioJson, commandContext, confi
     result,
   });
 
-  const text = formatScenarioReport(scenario);
+  const text = formatScenarioReport(scenario, coverage);
 
   return {
     status: "ok",
@@ -119,15 +115,29 @@ export function scenarioCommand(projectName, scenarioJson, commandContext, confi
 /**
  * Formats a scenario evaluation as terminal text.
  *
+ * The coverage line rides the same `coverageIncompleteReasons` clauses every
+ * other text face uses (`../verdict.mjs`), so a terminal reader is told how
+ * much of the tree the comparison inspected, in the one wording the JSON
+ * envelope's status also speaks (#609).
+ *
  * @param {object} scenario The scenario evaluation result.
+ * @param {object} coverage The run's coverage block.
  * @returns {string}
  */
-function formatScenarioReport(scenario) {
+function formatScenarioReport(scenario, coverage) {
   const lines = [];
 
   lines.push(`Scenario evaluation for "${scenario.project}"`);
   lines.push(`${"=".repeat(50)}`);
   lines.push(`Virtual: ${scenario.virtual}  |  Not authoritative: ${scenario.notAuthoritative}`);
+  // The "how much was inspected" line, derived from the same coverage block
+  // the envelope carries — never re-counted here.
+  lines.push(
+    `Coverage: ${coverage.imports} import${coverage.imports === 1 ? "" : "s"} in ` +
+      `${coverage.analyzedFiles} file${coverage.analyzedFiles === 1 ? "" : "s"} across ` +
+      `${coverage.projects} project${coverage.projects === 1 ? "" : "s"}` +
+      (coverage.complete ? "" : " — coverage incomplete"),
+  );
   lines.push("");
 
   if (scenario.changes.length > 0) {