@ecoma-io/archkeep 0.20.1 → 0.22.0

package/src/intent/intent-manifest.json

@@ -1,7 +1,7 @@
 {
   "version": 2,
   "generatedAt": "v1.0.0-hardening",
-  "description": "Machine-readable manifest declaring every v1.0 intent and the evidence that supports it. A contract is 'proven' only when at least one evidence entry is an executable proof (behavioral-test, e2e-test, or architecture-test). Source-evidence and documentation support the claim but cannot prove it alone.",
+  "description": "Machine-readable manifest declaring every v1.0 intent and the evidence that supports it. A contract is 'proven' only when at least one evidence entry is an executable proof (behavioral-test, e2e-test, or architecture-test). Source-evidence and documentation support the claim but cannot prove it alone. Every evidence entry carries the sha256 of the artifact it names, and the gate recomputes each digest, so evidence is content-addressed: an artifact that changed after its claim was certified is a loud mismatch, not a silent swap.",
   "evidenceTaxonomy": {
     "behavioral-test": "A unit or integration test that imports and calls the code, asserting on runtime behavior (not source text). Proves the intent is regression-protected.",
     "e2e-test": "A CLI subprocess test that exercises the real binary against a consumer workspace. Proves the intent holds end-to-end.",
@@ -19,12 +19,14 @@
         {
           "type": "architecture-test",
           "path": "src/conformance/boundary.test.mjs",
-          "assertion": "SHIPPED_PACKAGES allow-list prevents unapproved dependencies; specifiersIn() walk catches all imports including createRequire; no provider import found in core layers"
+          "assertion": "SHIPPED_PACKAGES allow-list prevents unapproved dependencies; specifiersIn() walk catches all imports including createRequire; no provider import found in core layers",
+          "sha256": "12d4e179f88de2622a41e56f42b2bab1c88a677ec2232430752138c57ba5fb18"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/context.mjs",
-          "assertion": "Only commands/context.mjs imports providers — the designated orchestration layer"
+          "assertion": "Only commands/context.mjs imports providers — the designated orchestration layer",
+          "sha256": "7f566c06afbb175337529bd9bdc42465f8849498b932abf6a77fe0290a0cd13c"
         }
       ],
       "status": "proven"
@@ -37,17 +39,20 @@
         {
           "type": "behavioral-test",
           "path": "src/report/json.test.mjs",
-          "assertion": "JSON envelope throws on status=ok + incomplete coverage, status/exitCode disagreement, coverage.complete/notAnalyzed disagreement"
+          "assertion": "JSON envelope throws on status=ok + incomplete coverage, status/exitCode disagreement, coverage.complete/notAnalyzed disagreement",
+          "sha256": "a371d36b89b10c5a4bda4d9e9a2e3bde114256c1377eb95699c9f0f195aabc4a"
         },
         {
           "type": "source-evidence",
           "path": "src/lsp/diagnose.mjs",
-          "assertion": "analyzed:false on every non-verdict path; empty diagnostic list only from two named places"
+          "assertion": "analyzed:false on every non-verdict path; empty diagnostic list only from two named places",
+          "sha256": "4eea19bf245c33963cd292e02f676eb9c5238a5783a3a960976f53afc7cf8b27"
         },
         {
           "type": "source-evidence",
           "path": "cli.mjs",
-          "assertion": "Exit codes 0/1/3 distinguish clean/findings/cannot-look"
+          "assertion": "Exit codes 0/1/3 distinguish clean/findings/cannot-look",
+          "sha256": "81abe8243660b3cca913ee903c1fc0bfcdb6a240640c5302f18848e6a9473fe6"
         }
       ],
       "status": "proven"
@@ -60,17 +65,26 @@
         {
           "type": "behavioral-test",
           "path": "src/intent/intent.test.mjs",
-          "assertion": "analysis output conforms to the frozen contract schema (no extra verdict/policy fields); analysis output is invariant under project tag changes; analysis source contains no judging vocabulary"
+          "assertion": "analysis output conforms to the frozen contract schema (no extra verdict/policy fields); analysis output is invariant under project tag changes (three workspaces differing only in project tag fields compared byte-for-byte)",
+          "sha256": "6ed86cb5e7af94b56fa2af3d2da5d45d58937fbbf316105da0224d0060e88582"
+        },
+        {
+          "type": "architecture-test",
+          "path": "src/intent/intent.test.mjs",
+          "assertion": "the gate walks every production analysis module and fails when judging vocabulary (judge/forbid/permit/allow/ban) appears in code",
+          "sha256": "6ed86cb5e7af94b56fa2af3d2da5d45d58937fbbf316105da0224d0060e88582"
         },
         {
           "type": "source-evidence",
           "path": "src/analysis/contract.md",
-          "assertion": "Analysis record is a superset of a graph edge — 5 of 15 violations decided on raw specifier"
+          "assertion": "Analysis record is a superset of a graph edge — 5 of 15 violations decided on raw specifier",
+          "sha256": "56d2db7816ba5ffc5fbe9e299f7d5e270a857b42eb54bd3bea7c05da17be595b"
         },
         {
           "type": "source-evidence",
           "path": "AGENTS.md",
-          "assertion": "src/graph/ is a lossy view of analysis, on purpose; src/analysis/ never judges"
+          "assertion": "src/graph/ is a lossy view of analysis, on purpose; src/analysis/ never judges",
+          "sha256": "3209154935cc1463127721203da74dc8bf8ba40258b182c5faa7345946611e38"
         }
       ],
       "status": "proven"
@@ -83,17 +97,20 @@
         {
           "type": "e2e-test",
           "path": "e2e/determinism.e2e.mjs",
-          "assertion": "Graph, check, impact run twice — byte-identical JSON output"
+          "assertion": "Graph, check, impact run twice — byte-identical JSON output",
+          "sha256": "90c0f2a62a111013990ff96ec07042e961c1aae50710c597192657cc270df5ec"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
-          "assertion": "Plain string comparison, never localeCompare; INTERNAL_DATA_FIELDS stripped; SCHEMA_VERSION = 2"
+          "assertion": "Plain string comparison, never localeCompare; INTERNAL_DATA_FIELDS stripped; SCHEMA_VERSION = 2",
+          "sha256": "cce9730e33e83e0a183c0139afcc9a0845f2f95f67b07875f9c583f3ca95d046"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
-          "assertion": "computePolicyFingerprint produces SHA-256 of canonicalized policy"
+          "assertion": "computePolicyFingerprint produces SHA-256 of canonicalized policy",
+          "sha256": "cce9730e33e83e0a183c0139afcc9a0845f2f95f67b07875f9c583f3ca95d046"
         }
       ],
       "status": "proven"
@@ -106,12 +123,14 @@
         {
           "type": "e2e-test",
           "path": "e2e/diff.e2e.mjs",
-          "assertion": "Invalid baseline schemaVersion exits 3; incompatible version exits 3"
+          "assertion": "Invalid baseline schemaVersion exits 3; incompatible version exits 3",
+          "sha256": "7892a6dc56f5e1ec725fd6d029bba76bc493d8c34790f346e15af0d7d0dbbdc1"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
-          "assertion": "parseBaseline validates schemaVersion; refuses unknown versions"
+          "assertion": "parseBaseline validates schemaVersion; refuses unknown versions",
+          "sha256": "6190013ec55eeb7f1a9e4cdd910c7be73bfb1fa87051bdeace7c9581c6a18426"
         }
       ],
       "status": "proven"
@@ -124,12 +143,14 @@
         {
           "type": "e2e-test",
           "path": "e2e/diff.e2e.mjs",
-          "assertion": "Self-baseline exits 0; added/removed edges reported; policy mismatch warned; rule-impact with config"
+          "assertion": "Self-baseline exits 0; added/removed edges reported; policy mismatch warned; rule-impact with config",
+          "sha256": "7892a6dc56f5e1ec725fd6d029bba76bc493d8c34790f346e15af0d7d0dbbdc1"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
-          "assertion": "computeDiff returns structural diff; policyMismatch detected via fingerprint; computeRuleImpact for depConstraints-only context"
+          "assertion": "computeDiff returns structural diff; policyMismatch detected via fingerprint; computeRuleImpact for depConstraints-only context",
+          "sha256": "6190013ec55eeb7f1a9e4cdd910c7be73bfb1fa87051bdeace7c9581c6a18426"
         }
       ],
       "status": "proven"
@@ -142,12 +163,14 @@
         {
           "type": "e2e-test",
           "path": "e2e/determinism.e2e.mjs",
-          "assertion": "Impact --format json produces identical output on two runs"
+          "assertion": "Impact --format json produces identical output on two runs",
+          "sha256": "90c0f2a62a111013990ff96ec07042e961c1aae50710c597192657cc270df5ec"
         },
         {
           "type": "behavioral-test",
           "path": "src/commands/impact.test.mjs",
-          "assertion": "Sorts results using plain string comparison (never localeCompare)"
+          "assertion": "Sorts results using plain string comparison (never localeCompare)",
+          "sha256": "b188d7001d146c203be490727414f0c585d8e589f10e3a9add40a34b5aedd532"
         }
       ],
       "status": "proven"
@@ -160,17 +183,20 @@
         {
           "type": "behavioral-test",
           "path": "src/commands/context-command.test.mjs",
-          "assertion": "Returns tags, matched constraints, per-edge violations; coverage.notes warns about depConstraints-only scope"
+          "assertion": "Returns tags, matched constraints, per-edge violations; coverage.notes warns about depConstraints-only scope",
+          "sha256": "eccd31e3057bbb0cb45785e0047e0d71e83dbbc00703ee231f085cf52fb76db8"
         },
         {
           "type": "e2e-test",
           "path": "e2e/context.e2e.mjs",
-          "assertion": "Native consumer: tags, constraints, coverage.notes verified; Moon consumer: context E2E"
+          "assertion": "Native consumer: tags, constraints, coverage.notes verified; Moon consumer: context E2E",
+          "sha256": "336994ea66e2b7b7ff1d374e3127b478d530508b8c8e5ef927805c5aa11b6cb8"
         },
         {
           "type": "documentation",
           "path": "../../docs/concepts/agentic-development.md",
-          "assertion": "Section 'What context and impact do not check' warns agents about the semantic gap"
+          "assertion": "Section 'What context and impact do not check' warns agents about the semantic gap",
+          "sha256": "a42bca1e927a59d28160eb947a285c20d1a6cc9633a69c91a45e9d46bbe1686b"
         }
       ],
       "status": "proven"
@@ -183,12 +209,14 @@
         {
           "type": "behavioral-test",
           "path": "src/commands/explain.test.mjs",
-          "assertion": "Returns all violations at a site; unresolvable site returns unresolvable:true with reason"
+          "assertion": "Returns all violations at a site; unresolvable site returns unresolvable:true with reason",
+          "sha256": "017581d978f277fadecedd6a4a0a4befca3743dbf2b084e1192792a1891466ad"
         },
         {
           "type": "e2e-test",
           "path": "e2e/explain.e2e.mjs",
-          "assertion": "Native and Moon consumers: specifier, sourceProject, targetProject, violations verified"
+          "assertion": "Native and Moon consumers: specifier, sourceProject, targetProject, violations verified",
+          "sha256": "857e198249c0614af643f784d985ae782ab8dfa9906f92f44193e2570ee0c343"
         }
       ],
       "status": "proven"
@@ -201,37 +229,44 @@
         {
           "type": "behavioral-test",
           "path": "src/intent/intent.test.mjs",
-          "assertion": "depConstraints verdicts from judgeEdge agree with evaluate; explain includes the same violations as evaluate at a given site; diff warns in coverage.notes when ruleImpact is computed"
+          "assertion": "depConstraints verdicts from judgeEdge agree with evaluate in both directions (violating edge found by both, legal edge reported by neither); explain includes the same violations as evaluate at a given site",
+          "sha256": "6ed86cb5e7af94b56fa2af3d2da5d45d58937fbbf316105da0224d0060e88582"
         },
         {
           "type": "behavioral-test",
           "path": "src/commands/context-command.test.mjs",
-          "assertion": "Test verifies coverage.notes contains depConstraints warning"
+          "assertion": "Test verifies coverage.notes contains depConstraints warning",
+          "sha256": "eccd31e3057bbb0cb45785e0047e0d71e83dbbc00703ee231f085cf52fb76db8"
         },
         {
           "type": "e2e-test",
           "path": "e2e/context.e2e.mjs",
-          "assertion": "E2E verifies coverage.notes in JSON envelope"
+          "assertion": "E2E verifies coverage.notes in JSON envelope",
+          "sha256": "336994ea66e2b7b7ff1d374e3127b478d530508b8c8e5ef927805c5aa11b6cb8"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/context-command.mjs",
-          "assertion": "coverage.notes warns that per-edge violations cover only depConstraints (3 of 15 violation types)"
+          "assertion": "coverage.notes warns that per-edge violations cover only depConstraints (3 of 15 violation types)",
+          "sha256": "72526cdaf038da4d9a50b33ab3cb30828713e62bbb891f4e2e51e008a403338e"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/impact.mjs",
-          "assertion": "coverage.notes warns that per-edge violations cover only depConstraints (3 of 15 violation types)"
+          "assertion": "coverage.notes warns that per-edge violations cover only depConstraints (3 of 15 violation types)",
+          "sha256": "38cff166a8944860c51a73316447ce789898751489d783e75fd6befbfd30be3c"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
-          "assertion": "coverage.notes warns when ruleImpact is computed (depConstraints only, 3 of 15)"
+          "assertion": "coverage.notes warns when ruleImpact is computed (depConstraints only, 3 of 15)",
+          "sha256": "6190013ec55eeb7f1a9e4cdd910c7be73bfb1fa87051bdeace7c9581c6a18426"
         },
         {
           "type": "documentation",
           "path": "../../docs/concepts/agentic-development.md",
-          "assertion": "Section warns agents: violations:[] means allowed by constraint table, not free of all boundary violations"
+          "assertion": "Section warns agents: violations:[] means allowed by constraint table, not free of all boundary violations",
+          "sha256": "a42bca1e927a59d28160eb947a285c20d1a6cc9633a69c91a45e9d46bbe1686b"
         }
       ],
       "status": "proven"
@@ -244,12 +279,14 @@
         {
           "type": "e2e-test",
           "path": "e2e/determinism.e2e.mjs",
-          "assertion": "Graph, check, impact: two runs produce byte-identical JSON"
+          "assertion": "Graph, check, impact: two runs produce byte-identical JSON",
+          "sha256": "90c0f2a62a111013990ff96ec07042e961c1aae50710c597192657cc270df5ec"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
-          "assertion": "Plain string comparison throughout; never localeCompare"
+          "assertion": "Plain string comparison throughout; never localeCompare",
+          "sha256": "cce9730e33e83e0a183c0139afcc9a0845f2f95f67b07875f9c583f3ca95d046"
         }
       ],
       "status": "proven"
@@ -262,22 +299,26 @@
         {
           "type": "e2e-test",
           "path": "e2e/parity.e2e.mjs",
-          "assertion": "Nx vs Native: project names, edge source/target/type, violation rule IDs, envelope structure"
+          "assertion": "Nx vs Native: project names, edge source/target/type, violation rule IDs, envelope structure",
+          "sha256": "106f59315e4661ae67f5c1e44895d56f7f7562eacd4c44101a9ed4b0e56f774e"
         },
         {
           "type": "e2e-test",
           "path": "e2e/moon.e2e.mjs",
-          "assertion": "Moon: check, graph, diff, impact, explain, context verified against Moon provider (conditional on moon CLI availability)"
+          "assertion": "Moon: check, graph, diff, impact, explain, context verified against Moon provider (conditional on moon CLI availability)",
+          "sha256": "8293a65ff407ea43a3985c742ae6333970ec3b0400f3df46189793a3dc87af6b"
         },
         {
           "type": "source-evidence",
           "path": "src/providers/moon.mjs",
-          "assertion": "inferWorkspaceLayout returns null for partial layouts — same all-or-nothing contract as Nx and Native"
+          "assertion": "inferWorkspaceLayout returns null for partial layouts — same all-or-nothing contract as Nx and Native",
+          "sha256": "232dd8e2cbe70c9149ba3a75a03dcebe0db355894c280964ebbf6a5a536b5567"
         },
         {
           "type": "behavioral-test",
           "path": "src/providers/moon.test.mjs",
-          "assertion": "Partial layout (apps-only, libs-only) returns undefined workspaceLayout"
+          "assertion": "Partial layout (apps-only, libs-only) returns undefined workspaceLayout",
+          "sha256": "084a0061b3236e680274d837fb2f12d27dd4b5a379040157f7afe2be5088e8ac"
         }
       ],
       "status": "proven"
@@ -290,17 +331,20 @@
         {
           "type": "behavioral-test",
           "path": "src/commands/drift.test.mjs",
-          "assertion": "driftCommand returns status ok with observed facts and findings; refuses incomplete coverage, absent intent, and unregistered-plugin incomplete graph; buildObserved counts implicit edges separately"
+          "assertion": "driftCommand returns status ok with observed facts and findings; refuses incomplete coverage, absent intent, and unregistered-plugin incomplete graph; buildObserved counts implicit edges separately",
+          "sha256": "dbb0dfa1ecce9123ad0a38cdd6bc97e6645a47cba78496357318375db952e43a"
         },
         {
           "type": "behavioral-test",
           "path": "src/report/drift-text.test.mjs",
-          "assertion": "formatDriftReport states comparison facts even when clean (no-drift is a claim about coverage); groups findings by rule in taxonomy order; byte-identical determinism"
+          "assertion": "formatDriftReport states comparison facts even when clean (no-drift is a claim about coverage); groups findings by rule in taxonomy order; byte-identical determinism",
+          "sha256": "767d395c40cb0fa61f19ec06d587708e4ba065323bb1ee170254365847b49cc5"
         },
         {
           "type": "e2e-test",
           "path": "e2e/drift.e2e.mjs",
-          "assertion": "Through the installed CLI: drift exits 0 on a matching tree and names fingerprint/rows; reports dependencyForbidden and projectMissing; JSON envelope carries findings; malformed intent exits 3 for both drift and check"
+          "assertion": "Through the installed CLI: drift exits 0 on a matching tree and names fingerprint/rows; reports dependencyForbidden and projectMissing; JSON envelope carries findings; malformed intent exits 3 for both drift and check",
+          "sha256": "1e060ba0f02497259fdde2481dc59bd74bf6658f2fc354100de4f89ff6ffb926"
         }
       ],
       "status": "proven"

package/src/report/json.mjs

@@ -94,12 +94,39 @@ export function jsonEnvelope({ command, context, status, exitCode, coverage, res
         `them disagree would make one of them a lie.`,
     );
   }
-  if (coverage.complete !== (coverage.notAnalyzed.length === 0)) {
+  // Completeness law, one-directional (#595, #599): `complete: true`
+  // claims the run judged everything its coverage block describes, and a
+  // whole-file failure or an unresolvable import site is exactly the kind
+  // of thing it did not judge — so the claim is refused over either. The
+  // reverse is deliberately allowed: `complete: false` with both lists
+  // empty is the zero-analysis state (a scope that selected no owned file,
+  // in-scope files no analyzer claims), which names its reason in the
+  // envelope's status and decision rather than in these lists, and refusing
+  // it would leave a run that judged nothing unable to say so. blindSpots
+  // is optional because not every command's coverage carries it; where it
+  // is present, the law is enforced.
+  //
+  // Within blindSpots only the unresolvable-LITERAL class counts as unjudged
+  // work (#595, narrowed): a row carrying `dynamic: true` is the declared
+  // non-literal-import limit — the language itself saying the target is
+  // computed at runtime, unknowable to static analysis in principle — and a
+  // declared limit is disclosed, not withheld over. The classifier lives once
+  // in `analysis/source-util.mjs`; this guard reads the row field the same
+  // helper that built the rows set, so the two can never disagree.
+  const blindSpotList = Array.isArray(coverage.blindSpots) ? coverage.blindSpots : [];
+  const unjudgedBlindSpots = blindSpotList.filter(
+    (row) => row.dynamic !== true && row.external !== true,
+  );
+  if (
+    coverage.complete === true &&
+    (coverage.notAnalyzed.length > 0 || unjudgedBlindSpots.length > 0)
+  ) {
     throw new Error(
-      `archkeep: refusing to build a JSON envelope where coverage.complete (${coverage.complete}) ` +
-        `disagrees with coverage.notAnalyzed (${coverage.notAnalyzed.length} entr${coverage.notAnalyzed.length === 1 ? "y" : "ies"}) ` +
-        `— the two must always agree, or a reader checking only one of them could mistake a partial ` +
-        `run for a complete one.`,
+      `archkeep: refusing to build a JSON envelope claiming coverage.complete (${coverage.complete}) ` +
+        `over unjudged work (notAnalyzed: ${coverage.notAnalyzed.length} entr${coverage.notAnalyzed.length === 1 ? "y" : "ies"}, ` +
+        `blindSpots: ${unjudgedBlindSpots.length}) — a run ` +
+        `that could not read everything cannot claim to have. This is a bug in the command that built ` +
+        `this envelope, not a fact about the workspace being judged.`,
     );
   }
   // A bare `null` decision is the same programming error as a hand-built

package/src/report/provenance-text.mjs

@@ -31,13 +31,9 @@
  *     created: string|null, updated: string|null, supersedes: string[],
  *     supersededBy: string[], bindings: string[],
  *     attribution: {createdBy: object|null, lastChangedBy: object|null}|null,
- *     attested: boolean, note: string|null}[]}} input
- *   `decisionRefTotal` is how many governance rows cite a `decisionRef` at
- *   all — the resolution section renders only when it is non-zero, the same
- *   "no fact, no claim" bargain every optional axis in this tool states.
- *   `decisionLifecycle` (optional, default `[]`) is the decision-lifecycle
- *   section — it renders only when non-empty.
- * @returns {string}
+ *     attested: boolean, note: string|null}[],
+ *   provenanceGraph?: {nodes: object[], edges: object[], claims: object[],
+ *     causalChains: object[]}|null}} input
  */
 export function formatProvenanceReport({
   establishment,
@@ -47,6 +43,7 @@ export function formatProvenanceReport({
   decisionRefTotal,
   unresolvedDecisionRefs,
   decisionLifecycle = [],
+  provenanceGraph = null,
 }) {
   const attestedCount = rowsTotal - unattested.length;
   const text = [];
@@ -140,5 +137,31 @@ export function formatProvenanceReport({
       );
     }
   }
+
+  // PR4 — provenance graph summary and one chain example
+  if (provenanceGraph !== null && provenanceGraph !== undefined) {
+    const nodeCount = provenanceGraph.nodes.length;
+    const edgeCount = provenanceGraph.edges.length;
+    const claimCount = provenanceGraph.claims.length;
+    const chainCount = provenanceGraph.causalChains.length;
+    text.push(
+      `graph     ${nodeCount} nodes, ${edgeCount} edges, ${claimCount} claims, ` +
+        `${chainCount} causal chain${chainCount === 1 ? "" : "s"}`,
+    );
+
+    // Show the first causal chain as an example (deterministic — sorted order)
+    if (chainCount > 0) {
+      const chain = provenanceGraph.causalChains[0];
+      text.push(
+        `chain     ${chain.id} — ${chain.hops.length} hop${chain.hops.length === 1 ? "" : "s"}`,
+      );
+      text.push(`  ${chain.startNode}`);
+      for (const hop of chain.hops) {
+        const evidence = hop.evidence.map((e) => e.detail).join("; ");
+        text.push(`  → ${hop.toNode}  (${hop.edgeKind}: ${evidence})`);
+      }
+    }
+  }
+
   return text.join("\n");
 }

package/src/report/text.mjs

@@ -21,7 +21,11 @@
  * wearing a formatter's name, and it would disagree with the engine the first
  * time either changed (`README.md` beside this file).
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  isDynamicSiteFailure,
+  isExternalSiteFailure,
+  isWholeFileFailure,
+} from "../analysis/source-util.mjs";
 
 /** Two spaces of indent for a violation's detail lines, four for wrapped text. */
 const DETAIL = "  ";
@@ -128,12 +132,19 @@ const formatFailure = (failure) =>
  * consequences and one heading for both hid that for as long as it existed.
  *
  * A SITE failure is a blind spot: the file was analyzed, and one specifier in
- * it is not statically knowable — `import(url)` with a computed argument is
- * the honest example, and so is a literal package import that names no
- * declared project and cannot resolve (an uninstalled third-party dependency:
- * a workspace with packages is a normal state, and failing the run on it would
- * block merges over dependencies nobody crossed). Both are legitimately
- * permanent, and the rest of the file still got a verdict.
+ * it is not statically knowable. Three classes, and the section says which
+ * class did what instead of leaving the exit code to be discovered. An
+ * unresolvable literal referencing the workspace's own surface — path-like,
+ * `#` subpath, `paths` alias — is a concrete question the resolver was asked
+ * about the governed graph and could not answer: it WITHHELD the verdict
+ * (exit 3 on a findings-free run, #595). An unresolvable bare-package
+ * specifier names no project the workspace declares — `external: true`, the
+ * resolvability question an installed dependency tree answers, which a
+ * workspace legitimately may not have (the native self-check's `git archive`
+ * copy is the measured case: 284 rows) — disclosed without withholding. A
+ * non-literal `import()`/`require()` argument is the language declaring the
+ * target computed at runtime — a declared limit, `dynamic: true`, disclosed
+ * without withholding.
  *
  * A WHOLE-FILE failure is a hole: nothing was read, parsed, or analyzed — or a
  * literal import that names a DECLARED project could not be resolved, so the
@@ -165,12 +176,42 @@ export function formatFailures(failures) {
   }
 
   if (blind.length > 0) {
+    const dyn = blind.filter(isDynamicSiteFailure).length;
+    const ext = blind.filter(isExternalSiteFailure).length;
+    const literal = blind.length - dyn - ext;
     sections.push(
       [
-        `${blind.length} import${blind.length === 1 ? "" : "s"} could not be resolved. ` +
-          `These are blind spots inside files that were analyzed, not verdicts — the run does not fail on them:`,
-        ...blind.map(formatFailure),
-      ].join("\n"),
+        `${blind.length} import${blind.length === 1 ? "" : "s"} could not be resolved — ` +
+          `blind spots inside files that were analyzed:`,
+        // All permanent classes are disclosed; the verdict treats them
+        // differently, and the report says which class did what instead of
+        // leaving the exit code to be discovered (the same posture the
+        // whole-file section's heading holds).
+        ...(literal > 0
+          ? [
+              `${literal} unresolvable literal import${literal === 1 ? "" : "s"} withheld the run's verdict (#595):`,
+            ]
+          : []),
+        ...blind
+          .filter((failure) => !isDynamicSiteFailure(failure) && !isExternalSiteFailure(failure))
+          .map(formatFailure),
+        ...(ext > 0
+          ? [
+              `${ext} unresolvable package import${ext === 1 ? "" : "s"} name${ext === 1 ? "s" : ""} ` +
+                `no project the workspace declares — external, disclosed without withholding:`,
+            ]
+          : []),
+        ...blind.filter(isExternalSiteFailure).map(formatFailure),
+        ...(dyn > 0
+          ? [
+              `${dyn} non-literal import() argument${dyn === 1 ? "" : "s"} — a declared limit static analysis cannot answer; ` +
+                `the verdict stands over the statically judgeable surface:`,
+            ]
+          : []),
+        ...blind.filter(isDynamicSiteFailure).map(formatFailure),
+      ]
+        .filter(Boolean)
+        .join("\n"),
     );
   }
   return sections.join("\n\n");
@@ -751,6 +792,27 @@ export function formatAcceptedViolations(waived, unresolvedDecisionRefs) {
   ].join("\n\n");
 }
 
+/**
+ * The could-not-look section: the reasons a run that found no violation is
+ * still not a pass, spelled the same way the JSON envelope words them
+ * (`../verdict.mjs`'s `coverageIncompleteReasons`, joined into
+ * `decision.reason`).
+ *
+ * "✔ no boundary violations" states only the boundary half of the verdict —
+ * on a run whose exit is 3, the reader needs the next lines to say WHY the
+ * run failed despite it, or the checkmark reads as a clean tree (P1-04's
+ * repro: an exit-3 run printed the checkmark and nothing else). Empty exactly
+ * when the run reached a verdict on everything it looked at.
+ *
+ * @param {string[]} coverageIncomplete The verdict's reason clauses, in
+ *   `verdictFor`'s pinned order.
+ * @returns {string} Empty exactly when there is nothing to disclose.
+ */
+export function formatCoverageIncomplete(coverageIncomplete) {
+  if (coverageIncomplete.length === 0) return "";
+  return coverageIncomplete.map((reason) => `⚠ ${reason}`).join("\n");
+}
+
 /**
  * The whole report, violations first.
  *
@@ -766,7 +828,7 @@ export function formatAcceptedViolations(waived, unresolvedDecisionRefs) {
  * summary line above only says "no boundary violations" when there is nothing
  * a waiver is covering either.
  *
- * @param {{violations: object[], failures: object[], analyzed: number, projects: number, imports: number, goWork?: object|null, tsconfigPaths?: object|null, declaredEdges?: object|null, intent?: object|null, fitness?: object|null, fitnessOverall?: {verdict: string}|null, customRules?: {decisions: object[], overall: {verdict: string}}|null, coverageGaps?: object[], notes?: string[], policy?: {profile: string|null, source: string, fingerprint: string}|null, unresolvedDecisionRefs?: Set<string>}} run
+ * @param {{violations: object[], failures: object[], analyzed: number, projects: number, imports: number, goWork?: object|null, tsconfigPaths?: object|null, declaredEdges?: object|null, intent?: object|null, fitness?: object|null, fitnessOverall?: {verdict: string}|null, customRules?: {decisions: object[], overall: {verdict: string}}|null, coverageGaps?: object[], notes?: string[], policy?: {profile: string|null, source: string, fingerprint: string}|null, unresolvedDecisionRefs?: Set<string>, coverageIncomplete?: string[]}} run
  * @returns {string}
  */
 export function formatReport({
@@ -786,6 +848,7 @@ export function formatReport({
   notes = [],
   policy = null,
   unresolvedDecisionRefs,
+  coverageIncomplete = [],
 }) {
   const inspected =
     `${imports} import${imports === 1 ? "" : "s"} in ${analyzed} file${analyzed === 1 ? "" : "s"} ` +
@@ -829,6 +892,13 @@ export function formatReport({
     }
   }
 
+  // The could-not-look reasons render BEFORE the per-feature sections, right
+  // after the verdict summary they qualify: a reader who just read "✔ no
+  // boundary violations" needs the next lines to be the reason the exit is
+  // still 3, not go.work bookkeeping.
+  const coverageIncompleteSection = formatCoverageIncomplete(coverageIncomplete);
+  if (coverageIncompleteSection !== "") sections.push(coverageIncompleteSection);
+
   const goWorkSection = formatGoWork(goWork);
   if (goWorkSection !== "") sections.push(goWorkSection);