ucn 5.5.2 → 5.6.0

package/core/output/analysis-ext.js

@@ -3,7 +3,8 @@
  */
 
 const { dynamicImportsNote, formatLineRanges, unverifiedReasonLabel, advisoryLine } = require('./shared');
-const { formatAccountLines, formatCalleeAccountLine, unverifiedCalleeLines, initializerReviewLines } = require('./analysis');
+const { paramFact } = require('../registry');
+const { formatAccountLines, formatSharedAccountLines, formatCalleeAccountLine, unverifiedCalleeLines, initializerReviewLines } = require('./analysis');
 
 /**
  * Format related command output - text
@@ -200,6 +201,8 @@ function formatDiffImpact(result, options = {}) {
 
     const lines = [];
     const MAX_CALLERS_PER_FN = options.all ? Infinity : 30;
+    const unverifiedLimit = options.all ? Infinity
+        : Number.isInteger(options.top) && options.top > 0 ? options.top : paramFact('top', 'unverifiedRows');
 
     lines.push(`Diff Impact Analysis (vs ${result.base})`);
     lines.push('═'.repeat(60));
@@ -262,7 +265,7 @@ function formatDiffImpact(result, options = {}) {
             // Unverified tier: visible one-liners with reasons (never silently dropped)
             const unverified = fn.unverifiedCallers || [];
             if (unverified.length > 0) {
-                const cap = options.all ? Infinity : 10;
+                const cap = unverifiedLimit;
                 lines.push(`  Unverified call sites (${unverified.length}) — call syntax, no binding/receiver evidence:`);
                 for (const u of unverified.slice(0, cap)) {
                     const caller = u.callerName ? ` [${u.callerName}]` : '';
@@ -275,11 +278,15 @@ function formatDiffImpact(result, options = {}) {
                 }
             }
 
-            // Conservation contract lines, indented inside the function block
-            for (const al of formatAccountLines(fn.account)) {
+            // Conservation contract lines, indented inside the function block.
+            // What holds for every symbol of the repository is said once,
+            // after the last function.
+            for (const al of formatAccountLines(fn.account, { shared: false })) {
                 lines.push(`  ${al}`);
             }
         }
+        const withAccount = result.functions.find(fn => fn.account);
+        if (withAccount) lines.push(...formatSharedAccountLines(withAccount.account));
     }
 
     // New functions
@@ -300,11 +307,12 @@ function formatDiffImpact(result, options = {}) {
             const remaining = fn.remainingCallSites || [];
             if (remaining.length > 0) {
                 lines.push(`  ⚠ still called from ${remaining.length} site(s) — name-level matches:`);
-                for (const site of remaining.slice(0, 10)) {
+                const cap = unverifiedLimit;
+                for (const site of remaining.slice(0, cap)) {
                     lines.push(`    ${site.relativePath}:${site.line}  ${site.content}`);
                 }
-                if (remaining.length > 10) {
-                    lines.push(`    ... and ${remaining.length - 10} more`);
+                if (remaining.length > cap) {
+                    lines.push(`    ... and ${remaining.length - cap} more`);
                 }
             }
         }
@@ -316,14 +324,16 @@ function formatDiffImpact(result, options = {}) {
         for (const symbol of result[key]) {
             lines.push(`  ${symbol.type} ${symbol.name} — ${symbol.relativePath}:${symbol.startLine}`);
             if (symbol.impact) {
-                lines.push(require('./analysis').formatImpact(symbol.impact, { compact: true }));
+                lines.push(require('./analysis').formatImpact(symbol.impact, { compact: true,
+                    all: options.all, top: options.top, allHint: options.allHint,
+                    evidenceBands: options.evidenceBands }));
             } else {
                 const refs = symbol.remainingReferences || [];
                 lines.push(`  Remaining name references: ${refs.length} unverified (deleted target)`);
-                for (const site of refs.slice(0, MAX_CALLERS_PER_FN)) {
+                for (const site of refs.slice(0, unverifiedLimit)) {
                     lines.push(`    ${site.file}:${site.line}: ${site.expression}`);
                 }
-                if (refs.length > MAX_CALLERS_PER_FN) lines.push(`    (+${refs.length - MAX_CALLERS_PER_FN} more)`);
+                if (refs.length > unverifiedLimit) lines.push(`    (+${refs.length - unverifiedLimit} more)`);
             }
         }
     }

package/core/output/analysis.js

@@ -5,7 +5,11 @@ const fs = require('fs');
 const path = require('path');
 const { langTraits } = require('../../languages');
 const { dynamicImportsNote, formatGitLine, unverifiedReasonLabel } = require('./shared');
+const { paramFact } = require('../registry');
 const { provenanceReplacer } = require('./provenance');
+const { matchLabelCounts, reasonList } = require('../source-universe');
+const { uncertaintyClassOf, partitionUnverified, runtimeFamilyKey } = require('../review-items');
+const { reasonSummaryLine } = require('../evidence-bands');
 
 /**
  * One short sentence (~80 chars) of a docstring, suitable for inline display
@@ -93,12 +97,43 @@ function formatAmbiguityCandidates(lines, ambiguity) {
     }
 }
 
+/**
+ * The account lines that hold for every symbol of the repository: paths
+ * nothing could be read from, so no name can be cleared against them. One
+ * line, with the reasons; the paths are listed in `repo` health.
+ */
+function formatSharedAccountLines(account) {
+    const opaque = account && account.opaque;
+    if (!opaque || opaque.count === 0) return [];
+    const sample = (opaque.sample || []).map(entry => `${entry.path} (${entry.reason})`);
+    const more = opaque.count - sample.length;
+    return [`WARNING: ${opaque.count} path${opaque.count === 1 ? '' : 's'} could not be searched ` +
+        `(${reasonList(opaque.reasons)}), so no name is cleared against ${opaque.count === 1 ? 'it' : 'them'}: ` +
+        `${sample.join(', ')}${more > 0 ? `, +${more} more` : ''}. See repo --sections=health.`];
+}
+
 /**
  * Render the conservation contract lines: ACCOUNT and CONTRACT (always),
- * WARNING (unparsed files containing the symbol), FILTERED (display-filter
+ * WARNING (what weakens the claim for THIS symbol), FILTERED (display-filter
  * hides). Returns [] when no account is present (e.g. class-type context).
+ *
+ * CONTRACT is a state, not a sentence. What the states never mean is the
+ * same for every answer and is stated where it is read once (the tool
+ * description, the usage guide, `repo` health): a complete text partition
+ * is not semantic completeness, and a zero is not deletion proof.
+ *   text-complete                      every literal-name line of project
+ *                                      source was classified;
+ *   text-complete, zero observed       ... and none is a use;
+ *   text-complete over indexed source  ... except lines in source UCN reads
+ *                                      but does not analyze, listed below;
+ *   degraded                           some line or path could not be
+ *                                      classified at all; see WARNING.
+ *
+ * `shared: false` leaves out the lines that hold for every symbol of the
+ * repository (paths nothing could be read from): a caller that prints many
+ * accounts prints those once, through formatSharedAccountLines.
  */
-function formatAccountLines(account) {
+function formatAccountLines(account, { shared = true } = {}) {
     if (!account) return [];
     const lines = [];
     const nc = account.nonCall || { imports: 0, definitions: 0, references: 0, unclassifiedText: 0, total: 0 };
@@ -107,7 +142,7 @@ function formatAccountLines(account) {
         `${account.confirmed} confirmed, ${account.unverified} unverified, ` +
         `${nc.total} non-call (${nc.imports} import, ${nc.definitions} definition, ${nc.references} reference, ${nc.unclassifiedText} other-text), ` +
         `${account.excluded ? account.excluded.total : 0} other-target, ` +
-        `${account.unsupported && account.unsupported.lines > 0 ? `${account.unsupported.lines} unsupported-language, ` : ''}` +
+        `${account.unsupported && account.unsupported.lines > 0 ? `${account.unsupported.lines} unanalyzed, ` : ''}` +
         `${account.unaccounted} unaccounted`;
     if (account.beyondText && account.beyondText.count > 0) {
         line += ` (+${account.beyondText.count} beyond-text caller${account.beyondText.count === 1 ? '' : 's'})`;
@@ -115,31 +150,31 @@ function formatAccountLines(account) {
     lines.push(line);
     const contract = account.contract || {};
     const unsupported = account.unsupported ||
-        { fileCount: 0, lines: 0, files: [], languages: {}, sites: [], sitesTruncated: false };
+        { fileCount: 0, lines: 0, files: [], languages: {}, reasons: {}, sites: [], sitesTruncated: false };
+    const opaqueCount = account.opaque ? account.opaque.count : 0;
     const textComplete = contract.textComplete !== undefined
         ? contract.textComplete
         : Boolean(account.conserved) && !(account.unparsed && account.unparsed.fileCount > 0) &&
             unsupported.lines === 0 &&
-            !(account.unreadableFiles && account.unreadableFiles.length > 0);
-    // When the ONLY gap is unsupported-language occurrences, say exactly that
-    // instead of the generic DEGRADED sentence: the partition over supported
-    // languages is still conserved, and the gap is enumerated below.
-    const unsupportedOnly = !textComplete && unsupported.lines > 0 &&
+            !(account.unreadableFiles && account.unreadableFiles.length > 0) &&
+            opaqueCount === 0;
+    // When the ONLY gap is occurrences in unanalyzed source, say exactly
+    // that: the partition over indexed source is still conserved, and the
+    // gap is enumerated below.
+    const unanalyzedOnly = !textComplete && unsupported.lines > 0 &&
         Boolean(account.conserved) &&
         !(account.unparsed && account.unparsed.fileCount > 0) &&
-        !(account.unreadableFiles && account.unreadableFiles.length > 0);
-    if (unsupportedOnly) {
-        const langs = Object.keys(unsupported.languages).join(', ');
-        lines.push(`CONTRACT: literal-name text partition complete over SUPPORTED languages only — ` +
-            `${unsupported.lines} line${unsupported.lines === 1 ? '' : 's'} in unsupported-language file${unsupported.fileCount === 1 ? '' : 's'}` +
-            `${langs ? ` (${langs})` : ''} NOT analyzed (see WARNING; verify with grep/ripgrep). ` +
-            'Semantic completeness is not claimed.');
+        !(account.unreadableFiles && account.unreadableFiles.length > 0) &&
+        opaqueCount === 0;
+    if (unanalyzedOnly) {
+        lines.push('CONTRACT: text-complete over indexed source; ' +
+            `${unsupported.lines} line${unsupported.lines === 1 ? '' : 's'} in unanalyzed source (see WARNING)`);
     } else if (!textComplete) {
-        lines.push('CONTRACT: literal-name text partition is DEGRADED; review WARNING and unaccounted lines before acting. Semantic completeness is not claimed.');
+        lines.push('CONTRACT: degraded; see WARNING');
     } else if (contract.observedTextZero) {
-        lines.push('CONTRACT: observed-text zero only; every literal-name line was classified, but aliases, indirect calls, generated code, and runtime dispatch may exist. Not safe-delete proof.');
+        lines.push('CONTRACT: text-complete, zero observed; not deletion proof');
     } else {
-        lines.push('CONTRACT: literal-name text partition complete; semantic completeness is not claimed (aliases, indirect calls, generated code, and runtime dispatch may exist).');
+        lines.push('CONTRACT: text-complete');
     }
     if (account.unparsed && account.unparsed.fileCount > 0) {
         lines.push(`WARNING: ${account.unparsed.fileCount} unparsed file${account.unparsed.fileCount === 1 ? '' : 's'} ` +
@@ -156,12 +191,11 @@ function formatAccountLines(account) {
             `${rec.lines > shown.length ? `, ... and ${rec.lines - shown.length} more` : ''}`);
     }
     if (unsupported.lines > 0) {
-        const langParts = Object.entries(unsupported.languages)
-            .map(([lang, count]) => `${lang}: ${count}`).join(', ');
+        const kinds = matchLabelCounts(unsupported);
         lines.push(`WARNING: ${unsupported.lines} line${unsupported.lines === 1 ? '' : 's'} in ` +
-            `${unsupported.fileCount} unsupported-language file${unsupported.fileCount === 1 ? '' : 's'} ` +
+            `${unsupported.fileCount} unanalyzed file${unsupported.fileCount === 1 ? '' : 's'} ` +
             `contain${unsupported.lines === 1 ? 's' : ''} "${account.symbol}"` +
-            `${langParts ? ` (${langParts})` : ''} — NOT analyzed; verify with grep/ripgrep:`);
+            `${kinds ? ` (${kinds})` : ''} — NOT analyzed; verify with grep/ripgrep:`);
         const shown = unsupported.sites.slice(0, 5);
         for (const site of shown) {
             lines.push(`  ${site.file}:${site.line}  ${site.text}`);
@@ -173,14 +207,7 @@ function formatAccountLines(account) {
     if (account.unreadableFiles && account.unreadableFiles.length > 0) {
         lines.push(`WARNING: ${account.unreadableFiles.length} unreadable file(s) skipped: ${account.unreadableFiles.join(', ')}`);
     }
-    if (account.skippedSources && account.skippedSources.length > 0) {
-        const shown = account.skippedSources.slice(0, 5)
-            .map(issue => `${issue.relativePath} (${issue.reason})`);
-        lines.push(`WARNING: ${account.skippedSources.length} source discovery gap(s) make this index partial: ${shown.join(', ')}`);
-        if (account.skippedSources.length > shown.length) {
-            lines.push(`  ... and ${account.skippedSources.length - shown.length} more; run repo --sections=health for the full reason set.`);
-        }
-    }
+    if (shared) lines.push(...formatSharedAccountLines(account));
     if (account.filtered && account.filtered.total > 0) {
         const parts = [];
         const f = account.filtered.byFlag || {};
@@ -192,6 +219,15 @@ function formatAccountLines(account) {
     return lines;
 }
 
+/**
+ * Rows an unverified list prints: every one with `all`, `top` when it was
+ * given, ten otherwise. The header always states the full count.
+ */
+function unverifiedRowCap(options) {
+    if (options?.all) return Infinity;
+    return Number.isInteger(options?.top) && options.top > 0 ? options.top : paramFact('top', 'unverifiedRows');
+}
+
 /**
  * Single-node CALLEE ACCOUNT line (context/smart — the per-def callee
  * contract from #223). Matches the tree rollup's arithmetic phrasing.
@@ -328,9 +364,7 @@ function formatContextJson(context) {
                     ...(c.dispatchVia && { dispatchVia: c.dispatchVia }),
                     ...(c.dispatchCandidates != null && { dispatchCandidates: c.dispatchCandidates }),
                     ...(c.externalContract && { externalContract: true }),
-                    uncertaintyClass: c.uncertaintyClass ||
-                        (c.reason === 'possible-dispatch' && c.dispatchVia
-                            ? 'runtime-dispatch' : 'actionable-ambiguity'),
+                    uncertaintyClass: uncertaintyClassOf(c),
                     ...(c.dispatchFamily && { dispatchFamily: c.dispatchFamily }),
                 })),
                 ...(context.ambiguityCandidates && {
@@ -391,9 +425,7 @@ function formatContextJson(context) {
                 ...(c.dispatchVia && { dispatchVia: c.dispatchVia }),
                 ...(c.dispatchCandidates != null && { dispatchCandidates: c.dispatchCandidates }),
                 ...(c.externalContract && { externalContract: true }),
-                uncertaintyClass: c.uncertaintyClass ||
-                    (c.reason === 'possible-dispatch' && c.dispatchVia
-                        ? 'runtime-dispatch' : 'actionable-ambiguity'),
+                uncertaintyClass: uncertaintyClassOf(c),
                 ...(c.dispatchFamily && { dispatchFamily: c.dispatchFamily }),
             })),
             ...(context.ambiguityCandidates && {
@@ -506,7 +538,9 @@ function formatContext(ctx, options = {}) {
         if (typeUnverified.length > 0) {
             lines.push(`\nCALLERS — UNVERIFIED (${typeUnverified.length}) — call or callable-reference syntax, no binding/receiver evidence:`);
             formatAmbiguityCandidates(lines, ctx.ambiguityCandidates);
-            const cap = 10;
+            const typeReasons = reasonSummaryLine(typeUnverified, options.evidenceBands);
+            if (typeReasons) lines.push(typeReasons);
+            const cap = unverifiedRowCap(ctx.meta);
             let shown = 0;
             for (const u of typeUnverified) {
                 if (shown >= cap) break;
@@ -628,20 +662,15 @@ function formatContext(ctx, options = {}) {
     // This separates unavoidable language semantics from ambiguity the agent
     // can investigate.
     const unverified = ctx.unverifiedCallers || [];
-    const runtimeDispatch = unverified.filter(u =>
-        u.uncertaintyClass === 'runtime-dispatch' ||
-        (u.reason === 'possible-dispatch' && u.dispatchVia));
-    const compileTimeDispatch = unverified.filter(u =>
-        u.uncertaintyClass === 'compile-time-dispatch');
-    const actionableUnverified = unverified.filter(u =>
-        u.uncertaintyClass !== 'compile-time-dispatch' &&
-        !(u.uncertaintyClass === 'runtime-dispatch' ||
-          (u.reason === 'possible-dispatch' && u.dispatchVia)));
+    // One classification for the text, the JSON and the review counts
+    // (core/review-items.js).
+    const {
+        runtime: runtimeDispatch, compileTime: compileTimeDispatch, actionable: actionableUnverified,
+    } = partitionUnverified(unverified);
     if (runtimeDispatch.length > 0) {
         const groups = new Map();
         for (const site of runtimeDispatch) {
-            const key = `${site.dispatchVia}\0${site.dispatchCandidates ?? ''}\0` +
-                `${site.externalContract ? 'external' : 'project'}`;
+            const key = runtimeFamilyKey(site);
             if (!groups.has(key)) groups.set(key, []);
             groups.get(key).push(site);
         }
@@ -732,11 +761,13 @@ function formatContext(ctx, options = {}) {
     }
 
     // Actionable ambiguity: call syntax without enough identity evidence.
-    // Always visible and capped at 10 one-liners unless --all.
+    // Always visible; ten one-liners unless --top or --all says otherwise.
     if (actionableUnverified.length > 0) {
         lines.push(`${compact ? '' : '\n'}CALLERS — UNVERIFIED (${actionableUnverified.length}) — call or callable-reference syntax, no binding/receiver evidence:`);
         formatAmbiguityCandidates(lines, ctx.ambiguityCandidates);
-        const cap = (ctx.meta && ctx.meta.all) ? Infinity : 10;
+        const reasons = reasonSummaryLine(actionableUnverified, options.evidenceBands);
+        if (reasons) lines.push(reasons);
+        const cap = unverifiedRowCap(ctx.meta);
         let shown = 0;
         for (const u of actionableUnverified) {
             if (shown >= cap) break;
@@ -862,6 +893,8 @@ function formatImpact(impact, options = {}) {
     }
 
     const compact = !!options.compact;
+    const allHint = options.allHint || 'use --all';
+    const unverifiedCap = unverifiedRowCap(options);
     const lines = [];
 
     // Header
@@ -970,14 +1003,14 @@ function formatImpact(impact, options = {}) {
             const reason = impact.propertyAccesses ? 'matching attribute syntax, receiver identity unresolved'
                 : 'matching value syntax, binding identity unresolved';
             lines.push(`${compact ? '' : '\n'}UNVERIFIED ${label} ACCESS CANDIDATES (${access.unverifiedSites.length}) — ${reason}:`);
-            for (const site of access.unverifiedSites.slice(0, 10)) {
+            for (const site of access.unverifiedSites.slice(0, unverifiedCap)) {
                 const caller = site.callerName ? ` [${site.callerName}]` : '';
                 const expr = site.expression ? `: ${site.expression.replace(/\s+/g, ' ').slice(0, 100)}` : '';
                 const why = impact.valueAccesses && site.reason ? ` (${site.reason})` : '';
                 lines.push(`  ${site.file}:${site.line}${caller} [${site.accessKind || 'access'}${Number.isInteger(site.column) ? `, column ${site.column + 1}` : ''}]${expr}${why}`);
             }
-            if (access.unverifiedSites.length > 10) {
-                lines.push(`  (+${access.unverifiedSites.length - 10} more unverified)`);
+            if (access.unverifiedSites.length > unverifiedCap) {
+                lines.push(`  (+${access.unverifiedSites.length - unverifiedCap} more unverified — ${allHint})`);
             }
         }
         const valueAccount = impact.valueAccesses?.account;
@@ -999,21 +1032,23 @@ function formatImpact(impact, options = {}) {
         }
         if (refs.unverifiedSites.length > 0) {
             lines.push(`${compact ? '' : '\n'}UNVERIFIED TYPE REFERENCE CANDIDATES (${refs.unverifiedSites.length}) — the name, the type lookup cannot decide what it names:`);
-            for (const site of refs.unverifiedSites.slice(0, 10)) {
+            for (const site of refs.unverifiedSites.slice(0, unverifiedCap)) {
                 const expr = site.expression ? `: ${site.expression.replace(/\s+/g, ' ').slice(0, 100)}` : '';
                 lines.push(`  ${site.file}:${site.line} [${position(site)}]${expr} (${site.reason})`);
             }
-            if (refs.unverifiedSites.length > 10) {
-                lines.push(`  (+${refs.unverifiedSites.length - 10} more unverified)`);
+            if (refs.unverifiedSites.length > unverifiedCap) {
+                lines.push(`  (+${refs.unverifiedSites.length - unverifiedCap} more unverified — ${allHint})`);
             }
         }
         if (refs.account) lines.push(formatTypeAccount(impact.function, refs));
     }
 
-    // Unverified tier: visible, capped at 10 one-liners
+    // Unverified tier: visible; ten one-liners unless --top or --all says otherwise
     if (impactUnverified.length > 0) {
         lines.push(`${compact ? '' : '\n'}UNVERIFIED CALL SITES (${impactUnverified.length}) — call or callable-reference syntax, no binding/receiver evidence:`);
-        const cap = 10;
+        const reasons = reasonSummaryLine(impactUnverified, options.evidenceBands);
+        if (reasons) lines.push(reasons);
+        const cap = unverifiedCap;
         for (const site of impactUnverified.slice(0, cap)) {
             const caller = site.callerName ? ` [${site.callerName}]` : '';
             const reason = site.reason ? ` (${unverifiedReasonLabel(site)})` : '';
@@ -1021,7 +1056,7 @@ function formatImpact(impact, options = {}) {
             lines.push(`  ${site.file}:${site.line}${caller}${expr}${reason}`);
         }
         if (impactUnverified.length > cap) {
-            lines.push(`  (+${impactUnverified.length - cap} more unverified)`);
+            lines.push(`  (+${impactUnverified.length - cap} more unverified — ${allHint})`);
         }
     }
 
@@ -1171,6 +1206,8 @@ function formatAbout(about, options = {}) {
     if (aboutUnverified && aboutUnverified.total > 0) {
         lines.push('');
         lines.push(`CALLERS — UNVERIFIED (${aboutUnverified.total}) — call or callable-reference syntax, no binding/receiver evidence:`);
+        const reasons = reasonSummaryLine(aboutUnverified.reasons || aboutUnverified.top, options.evidenceBands);
+        if (reasons) lines.push(reasons);
         for (const u of aboutUnverified.top) {
             const caller = u.callerName ? ` [${u.callerName}]` : '';
             const reason = u.reason ? ` (${unverifiedReasonLabel(u)})` : '';
@@ -1325,6 +1362,7 @@ module.exports = {
     // Shared with output/tracing.js: the tree commands render the same
     // root-hop ACCOUNT/WARNING/FILTERED lines as context/impact.
     formatAccountLines,
+    formatSharedAccountLines,
     // Shared with output/analysis-ext.js (smart): single-node callee contract.
     formatCalleeAccountLine,
     unverifiedCalleeLines,

package/core/output/check.js

@@ -1,14 +1,74 @@
 /**
  * core/output/check.js — Pre-commit check formatter.
+ *
+ * Items are grouped by verdict, worst first: what broke, what to look at,
+ * what nothing depends on. Every site of a break is listed: a reader who
+ * has to fix thirteen call sites needs thirteen lines.
  */
 
 'use strict';
 
+const SECTIONS = [
+    ['blocked', 'BLOCKED', 'a break was observed'],
+    ['review', 'REVIEW', 'can reach existing code; not settled by the engine'],
+    ['ready', 'READY', 'nothing that existed depends on the change'],
+];
+// Occurrences of a name are context, not a worklist: a head is enough.
+const NAME_SITE_LIMIT = 10;
+
+function callersText(it) {
+    if (it.kind === 'module') return '';
+    let callers = it.callerCount != null ? `${it.callerCount} caller${it.callerCount === 1 ? '' : 's'}` : '';
+    if (it.unverifiedCallerCount > 0) callers += ` (+${it.unverifiedCallerCount} unverified)`;
+    return callers;
+}
+
+function itemLines(it) {
+    const tags = [];
+    if (it.kind && it.kind !== 'changed') tags.push(it.kind.toUpperCase());
+    if (it.verdict === 'ready' && it.kind === 'modified') {
+        if (it.change === 'inert') tags.push('contract unchanged');
+        else if (it.noDependents) tags.push('no static dependents');
+    }
+    if (it.verdict !== 'ready') {
+        for (const reason of it.reasons || []) if (reason !== 'signature-mismatch') tags.push(reason);
+    }
+    if (it.signatureMismatches > 0) tags.push(`SIG-DRIFT(${it.signatureMismatches})`);
+    if (it.orphan) tags.push('ORPHAN');
+    if (it.symbolType) tags.push(it.symbolType);
+    // Caller evidence matters where the callers do.
+    if (it.verdict !== 'ready' && it.kind !== 'deleted' && it.account && !it.account.textComplete) {
+        tags.push('ACCOUNT-INCOMPLETE');
+    }
+    const lines = [`  ${it.name} (${it.file}:${it.line})${tags.length ? ` [${tags.join(', ')}]` : ''}  ${callersText(it)}`.trimEnd()];
+    if (it.symbolType) {
+        lines.push(`    Dependencies: ${it.dependencyCount || 0} confirmed, ${it.unverifiedDependencyCount || 0} unverified`);
+    }
+    for (const m of it.mismatches || []) {
+        const problem = m.expected ? `expected ${m.expected}, got ${m.actual}` : (m.reason || 'arity mismatch');
+        const where = m.file ? `${m.file}:${m.line}` : '';
+        const expression = m.expression ? `  ${String(m.expression).trim()}` : '';
+        lines.push(`    ↳ ${where}${expression}  ${problem}${m.unchecked ? '  (not checked by the toolchain)' : ''}`);
+    }
+    const sites = it.sites || [];
+    const definite = it.verdict === 'blocked';
+    const shown = definite ? sites : sites.slice(0, NAME_SITE_LIMIT);
+    for (const site of shown) {
+        lines.push(`    ↳ ${site.file}${site.line ? `:${site.line}` : ''}${site.kind ? `  ${site.kind}` : ''}` +
+            `${site.unchecked ? '  (not checked by the toolchain)' : ''}`);
+    }
+    if (sites.length > shown.length) lines.push(`    (+${sites.length - shown.length} more occurrence(s))`);
+    return lines;
+}
+
 function formatCheck(result) {
     if (!result) return 'No check result.';
     if (result.ok === false) {
         // The gate could not run — never render this like a clean tree.
-        return `Pre-commit Check (${result.base}${result.staged ? ', staged' : ''})\n${'═'.repeat(60)}\nCHECK DID NOT RUN [${result.status || 'diff-failed'}] — ${result.error || 'git diff failed'}\nThis is not a pass. Fix the git context (run inside a git repository with a valid base ref) and rerun.`;
+        const advice = result.status === 'staged-snapshot-unavailable'
+            ? 'This is not a pass, and says nothing about the worktree. Resolve what keeps the git index from being exported (unmerged paths, a missing object) and rerun.'
+            : 'This is not a pass. Fix the git context (run inside a git repository with a valid base ref) and rerun.';
+        return `Pre-commit Check (${result.base}${result.staged ? ', staged' : ''})\n${'═'.repeat(60)}\nCHECK DID NOT RUN [${result.status || 'diff-failed'}] — ${result.error || 'git diff failed'}\n${advice}`;
     }
     const pathNotes = [];
     if (result.nonSourcePaths > 0) pathNotes.push(`Note: ${result.nonSourcePaths} changed path(s) outside supported source files not analyzed.`);
@@ -21,20 +81,26 @@ function formatCheck(result) {
     lines.push(`Pre-commit Check vs ${result.base}${result.staged ? ' (staged)' : ''}`);
     lines.push('═'.repeat(60));
     lines.push(...pathNotes);
+    for (const note of result.notes || []) lines.push(`Note: ${note}`);
+    const items = result.changed || [];
     if (result.trust) {
-        lines.push(`TRUST: ${result.trust.status} — UCN evidence is not semantic proof; compiler and tests are required`);
-        const trustDetails = [];
-        if (result.trust.incompleteAccounts) trustDetails.push(`${result.trust.incompleteAccounts} incomplete account(s)`);
-        if (result.trust.unverifiedCallSites) trustDetails.push(`${result.trust.unverifiedCallSites} unverified caller(s)`);
-        if (result.trust.signatureMismatches) trustDetails.push(`${result.trust.signatureMismatches} signature mismatch(es)`);
-        if (result.trust.filteredEdges) trustDetails.push(`${result.trust.filteredEdges} filtered edge(s)`);
-        if (result.trust.usageReviewSymbols) trustDetails.push(`${result.trust.usageReviewSymbols} symbol(s) need usages review`);
-        if (result.trust.unvalidatedDeclarations) trustDetails.push(`${result.trust.unvalidatedDeclarations} declaration change(s) need toolchain validation`);
-        if (trustDetails.length > 0) lines.push(`  ${trustDetails.join(' · ')}`);
+        const trust = result.trust;
+        lines.push(`TRUST: ${trust.status} — UCN evidence is not semantic proof; compiler and tests are required`);
+        const counts = [];
+        if (trust.blocked) counts.push(`${trust.blocked} blocked`);
+        if (trust.review) counts.push(`${trust.review} to review`);
+        if (trust.ready) counts.push(`${trust.ready} ready`);
+        const details = [];
+        if (trust.signatureMismatches) details.push(`${trust.signatureMismatches} signature mismatch(es)`);
+        if (trust.unverifiedCallSites) details.push(`${trust.unverifiedCallSites} unverified caller(s)`);
+        if (trust.incompleteAccounts) details.push(`${trust.incompleteAccounts} incomplete account(s)`);
+        if (trust.filteredEdges) details.push(`${trust.filteredEdges} filtered edge(s)`);
+        if (trust.usageReviewSymbols) details.push(`${trust.usageReviewSymbols} symbol(s) need usages review`);
+        if (trust.unvalidatedDeclarations) details.push(`${trust.unvalidatedDeclarations} declaration change(s) need toolchain validation`);
+        if (trust.strict) details.push('strict: review does not pass');
+        if (counts.length > 0 || details.length > 0) lines.push(`  ${[...counts, ...details].join(' · ')}`);
     }
 
-    // Changed functions section
-    const items = result.changed || [];
     const noun = items.some(it => it.symbolType) ? 'symbol' : 'function';
     if (result.truncated) {
         lines.push(`Changed: ${items.length} of ${result.totalChanged} ${noun}s`);
@@ -44,38 +110,28 @@ function formatCheck(result) {
     if (items.length === 0) {
         lines.push('  (none — only non-function changes)');
     } else {
-        for (const it of items) {
-            const tags = [];
-            if (it.kind && it.kind !== 'changed') tags.push(it.kind.toUpperCase());
-            if (it.signatureMismatches > 0) tags.push(`SIG-DRIFT(${it.signatureMismatches})`);
-            if (it.orphan) tags.push('ORPHAN');
-            if (it.symbolType) tags.push(it.symbolType);
-            if (it.account && !it.account.textComplete) tags.push('ACCOUNT-INCOMPLETE');
-            const tagStr = tags.length ? ' [' + tags.join(', ') + ']' : '';
-            let callers = it.callerCount != null ? `${it.callerCount} caller${it.callerCount === 1 ? '' : 's'}` : '';
-            if (it.unverifiedCallerCount > 0) {
-                callers += ` (+${it.unverifiedCallerCount} unverified)`;
-            }
-            lines.push(`  ${it.name} (${it.file}:${it.line})${tagStr}  ${callers}`);
-            if (it.symbolType) lines.push(`    Dependencies: ${it.dependencyCount || 0} confirmed, ${it.unverifiedDependencyCount || 0} unverified`);
-            if (it.mismatches && it.mismatches.length > 0) {
-                for (const m of it.mismatches.slice(0, 3)) {
-                    const where = m.file ? ` at ${m.file}:${m.line}` : '';
-                    const reason = m.expected
-                        ? `expected ${m.expected}, got ${m.actual}`
-                        : (m.reason || 'arity mismatch');
-                    lines.push(`    ↳ ${reason}${where}`);
-                }
-            }
+        for (const [verdict, title, meaning] of SECTIONS) {
+            const group = items.filter(it => (it.verdict || 'review') === verdict);
+            if (group.length === 0) continue;
+            lines.push(`${title} (${group.length}) — ${meaning}:`);
+            for (const it of group) lines.push(...itemLines(it));
         }
     }
 
     // Tests
     lines.push('');
     if (result.testFiles && result.testFiles.length > 0) {
-        lines.push(`Tests potentially affected: ${result.totalTests || result.testFiles.length} in ${result.testFiles.length} file${result.testFiles.length === 1 ? '' : 's'}`);
+        const files = result.testFiles.length;
+        // A count of tests is printed only when tests were counted: files
+        // whose tests are not read have none to report.
+        // "at least": a file among them holds tests that are not listed.
+        const conditional = result.conditionalTests ? ` (${result.conditionalTests} conditional)` : '';
+        lines.push(result.totalTests > 0
+            ? `Tests potentially affected: ${result.moreTests ? 'at least ' : ''}${result.totalTests} in ${files} file${files === 1 ? '' : 's'}${conditional}`
+            : `Test files potentially affected: ${files}${result.moreTests ? ' (tests not listed)' : ''}`);
         for (const tf of result.testFiles.slice(0, 8)) {
-            const cnt = tf.testCount ? ` (${tf.testCount})` : '';
+            const cnt = tf.testCount ? ` (${tf.moreTests ? 'at least ' : ''}${tf.testCount})`
+                : tf.moreTests ? ' (tests not listed)' : '';
             lines.push(`  ${tf.file}${cnt}`);
         }
         if (result.testFiles.length > 8) {
@@ -84,6 +140,11 @@ function formatCheck(result) {
     } else {
         lines.push('Tests: none detected for changed functions');
     }
+    if (result.supportFiles && result.supportFiles.length > 0) {
+        const names = result.supportFiles.slice(0, 5).map(row => row.file).join(', ');
+        const more = result.supportFiles.length > 5 ? `, +${result.supportFiles.length - 5} more` : '';
+        lines.push(`Test support code reached (declares no test, runs with the tests that load it): ${names}${more}`);
+    }
 
     // Action items
     if (result.actions && result.actions.length > 0) {

package/core/output/doctor.js

@@ -116,7 +116,15 @@ function formatDoctor(result, options = {}) {
                 const reasons = Object.entries(info.reasons || {})
                     .map(([reason, count]) => `${reason} ${count}`).join(', ');
                 lines.push(`  ${label}: ${fileCount} path${fileCount === 1 ? '' : 's'} not indexed${reasons ? ` (${reasons})` : ''}`);
-                lines.push('    The index is partial; adjust .ucn.json or discovery limits before relying on completeness-sensitive commands.');
+                const unsearchable = info.unsearchable || 0;
+                if (unsearchable > 0) {
+                    lines.push(`    ${unsearchable} could not be searched: no caller account is complete until ` +
+                        'they can be read (fix the path, raise the limit, or declare it in .ucn.json outsideProject).');
+                }
+                if (fileCount > unsearchable) {
+                    lines.push(`    ${unsearchable > 0 ? 'The rest is searched' : 'Searched'} as text for each name: ` +
+                        'an occurrence there is listed, not analyzed.');
+                }
             } else {
                 lines.push(`  ${label}: ${info.count} ${unit}${info.count === 1 ? '' : 's'} in ${fileCount} file${fileCount === 1 ? '' : 's'}`);
             }
@@ -129,6 +137,31 @@ function formatDoctor(result, options = {}) {
     }
     if (!anyBlindSpot) lines.push('  (none detected)');
 
+    // What a completeness claim ranges over and what it never means: said
+    // here once, so an answer only carries its own state.
+    lines.push('');
+    lines.push('Contract scope:');
+    const scope = result.scope;
+    if (scope) {
+        const list = reasons => Object.entries(reasons || {})
+            .map(([reason, count]) => `${reason} ${count}`).join(', ');
+        lines.push(`  Indexed source, plus ${scope.textOnly.count} file${scope.textOnly.count === 1 ? '' : 's'} ` +
+            `searched as text for each name${scope.textOnly.count > 0 ? ` (${list(scope.textOnly.reasons)})` : ''}.`);
+        if (scope.opaque.count > 0) {
+            lines.push(`  Not searchable: ${scope.opaque.count} path${scope.opaque.count === 1 ? '' : 's'} ` +
+                `(${list(scope.opaque.reasons)}); every caller account is degraded until they are.`);
+        }
+        if (scope.outside.count > 0) {
+            const sample = scope.outside.sample.slice(0, 3).map(entry => entry.path).join(', ');
+            lines.push(`  Outside the project: ${scope.outside.count} path${scope.outside.count === 1 ? '' : 's'} ` +
+                `(${list(scope.outside.reasons)}), no part of any claim: ${sample}` +
+                `${scope.outside.count > 3 ? ', ...' : ''}`);
+        }
+    }
+    lines.push('  CONTRACT text-complete: every literal-name line in that scope was classified.');
+    lines.push('  It is never semantic completeness (aliases, indirect calls, generated code and');
+    lines.push('  runtime dispatch may exist), and a zero is never deletion proof.');
+
     // Task-specific readiness. One scalar cannot honestly describe navigation,
     // refactoring, and deletion risk.
     lines.push('');

package/core/output/find.js

@@ -10,9 +10,10 @@ const {
 } = require('./shared');
 
 const { formatSymbolHandle } = require('../shared');
+const { paramFact } = require('../registry');
 
 // Detailed text rows shown by default; the rest are counted.
-const DEFAULT_DISPLAY_LIMIT = 5;
+const DEFAULT_DISPLAY_LIMIT = paramFact('limit', 'findDetail');
 
 /**
  * Trim a docstring to a single short sentence (max 80 chars) for inline display.