@ecoma-io/archkeep 0.21.0 → 0.22.1

package/src/commands/change.mjs

@@ -71,30 +71,37 @@
  * 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 {
   CONSTRAINT_ORDER,
   CONSTRAINT_ROW_NAMES,
+  edgePairKey,
   findChangeIntentReferenceViolations,
   readChangeIntent,
 } 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";
@@ -107,6 +114,7 @@ import { referenceTime } from "../governance/clock.mjs";
 import {
   classifyEvolution,
   declarationDigest,
+  escapeIdentityField,
   eventDedupeKey,
   eventId,
   EVOLUTION_EVENT_SCHEMA_VERSION,
@@ -145,27 +153,26 @@ function cmpFacts(a, b) {
  * The identity string a delta-classified violation entry carries into the
  * event's `findings` — the same identity fields the delta classification
  * emits (`messageId`, `sourceProject`, `target`), serialized deterministically
- * so the ref is stable across runs over the same transition.
+ * so the ref is stable across runs over the same transition. Fields are
+ * escaped through `escapeIdentityField`, so a `:` inside a project name no
+ * longer reads as the field separator and two distinct entries never share
+ * one id (#628). The sentinel is the ONE literal written unescaped: it is
+ * this function's own spelling for "absent", so a source project literally
+ * named `-` escapes to `\-` instead of merging with it — while an absent
+ * source project still spells exactly what earlier versions spelled, byte
+ * for byte.
  *
- * @param {{messageId: string, sourceProject: string|null, target: string}} entry
- * @returns {string}
- */
-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.
+ * Exported as the ONE spelling of this id — the same arrangement
+ * `edgeEvolutionIdentity` holds for edge identity — so a consumer composing
+ * the command layer cannot grow a second one that drifts.
  *
- * @param {{source: string, target: string, type?: string}} edge
+ * @param {{messageId: string, sourceProject: string|null, target: string}} entry
  * @returns {string}
  */
-function edgeIdentityString(edge) {
-  return `${edge.source}>${edge.target}${edge.type === undefined || edge.type === "" ? "" : `:${edge.type}`}`;
+export function violationFindingId(entry) {
+  const sourceProject =
+    entry.sourceProject == null ? "-" : escapeIdentityField(entry.sourceProject);
+  return `${escapeIdentityField(entry.messageId)}:${sourceProject}:${escapeIdentityField(entry.target)}`;
 }
 
 /**
@@ -173,6 +180,11 @@ function edgeIdentityString(edge) {
  * 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 +201,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:
@@ -240,9 +252,13 @@ function observedFrom(structural, meta) {
 export function reconcileMaterialDelta(intent, delta) {
   const addedProjectNames = new Set(intent.projects.add);
   const removedProjectNames = new Set(intent.projects.remove);
-  const edgeKey = ({ from, to }) => `${from}\u0000${to}`;
-  const addEdgeKeys = new Set(intent.edges.add.map(edgeKey));
-  const removeEdgeKeys = new Set(intent.edges.remove.map(edgeKey));
+  // The declared row's identity is `./change-intent.mjs`'s `edgePairKey` — the
+  // ONE spelling, shared with the grammar's own duplicate detection. A local
+  // spelling here was the live defect (#613): it agreed byte-for-byte until a
+  // shape moved, and the reconciliation would then stop recognizing the
+  // declarations it was handed while every command-local test stayed green.
+  const addEdgeKeys = new Set(intent.edges.add.map(edgePairKey));
+  const removeEdgeKeys = new Set(intent.edges.remove.map(edgePairKey));
 
   /** @type {object[]} */
   const matched = [];
@@ -266,7 +282,7 @@ export function reconcileMaterialDelta(intent, delta) {
       to: edge.target,
       type: edge.type,
     });
-    if (addEdgeKeys.has(edgeKey({ from: edge.source, to: edge.target }))) matched.push(row);
+    if (addEdgeKeys.has(edgePairKey({ from: edge.source, to: edge.target }))) matched.push(row);
     else unexpected.push(row);
   }
   for (const edge of delta.removedEdges) {
@@ -276,7 +292,7 @@ export function reconcileMaterialDelta(intent, delta) {
       to: edge.target,
       type: edge.type,
     });
-    if (removeEdgeKeys.has(edgeKey({ from: edge.source, to: edge.target }))) matched.push(row);
+    if (removeEdgeKeys.has(edgePairKey({ from: edge.source, to: edge.target }))) matched.push(row);
     else unexpected.push(row);
   }
   // No declaration surface in this version: a metadata change to a project
@@ -295,10 +311,10 @@ export function reconcileMaterialDelta(intent, delta) {
   const observedAdded = new Set(delta.addedProjects.map((p) => p.name));
   const observedRemoved = new Set(delta.removedProjects.map((p) => p.name));
   const observedAddEdges = new Set(
-    delta.addedEdges.map((edge) => edgeKey({ from: edge.source, to: edge.target })),
+    delta.addedEdges.map((edge) => edgePairKey({ from: edge.source, to: edge.target })),
   );
   const observedRemoveEdges = new Set(
-    delta.removedEdges.map((edge) => edgeKey({ from: edge.source, to: edge.target })),
+    delta.removedEdges.map((edge) => edgePairKey({ from: edge.source, to: edge.target })),
   );
 
   // Declared but never observed — the unfulfilled half, kept apart from
@@ -316,12 +332,12 @@ export function reconcileMaterialDelta(intent, delta) {
     }
   }
   for (const edge of intent.edges.add) {
-    if (!observedAddEdges.has(edgeKey(edge))) {
+    if (!observedAddEdges.has(edgePairKey(edge))) {
       missingExpected.push(factRow({ kind: "edge-added", from: edge.from, to: edge.to }));
     }
   }
   for (const edge of intent.edges.remove) {
-    if (!observedRemoveEdges.has(edgeKey(edge))) {
+    if (!observedRemoveEdges.has(edgePairKey(edge))) {
       missingExpected.push(factRow({ kind: "edge-removed", from: edge.from, to: edge.to }));
     }
   }
@@ -490,8 +506,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 +552,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 +756,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 +788,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,