ucn 5.1.1 → 5.2.1

package/core/command-contracts.js

@@ -140,21 +140,21 @@ const COMMAND_CONTRACTS = Object.freeze({
     }),
     impact: contract({
         question: 'What indexed code may be affected by changing this symbol or Git diff?',
-        purpose: 'List direct symbol call sites or compose repository impact from changed lines.',
+        purpose: 'List direct symbol dependencies or compose repository impact from changed lines.',
         target: 'Optional symbol/handle. Omitting it selects Git-diff mode.',
         modes: [
-            { name: 'symbol', when: 'A symbol target is supplied.', answer: 'Tiered direct call sites grouped by file with patterns/accounting.' },
+            { name: 'symbol', when: 'A symbol target is supplied.', answer: 'Tiered direct call sites grouped by file with patterns/accounting; accessor targets also list receiver-tiered property reads/writes.' },
             { name: 'diff', when: 'No symbol is supplied; `base` or `staged` selects the diff.', answer: 'Changed definitions and their composed impact.' },
         ],
         defaults: ['Symbol output is compact.', 'Diff base defaults to the repository default used by the Git analysis layer.'],
-        truth: 'Symbol impact is static tiered caller evidence; diff impact composes indexed changed definitions and does not imply runtime reachability completeness.',
+        truth: 'Symbol impact is static tiered caller evidence plus a separate accessor-dependency band where applicable; diff impact composes indexed changed definitions and does not imply runtime reachability completeness.',
         nonGoals: ['Automatic edits.', 'Behavioral equivalence or deployment impact.'],
         invalidCombinations: [
             'A named symbol cannot also select staged/diff scope.',
             '`base` and `staged` cannot both select the diff.',
         ],
         examples: ['ucn impact src/parser.ts:42:parseRequest', 'ucn impact --staged'],
-        jsonData: 'Symbol mode returns call sites/accounting; diff mode returns changed functions and aggregate impact.',
+        jsonData: 'Symbol mode returns call sites/accounting and optional property-access dependencies; diff mode returns changed functions and aggregate impact.',
         output: 'Potentially broad; narrow symbol mode by file/exclude and diff mode by a focused base.',
         next: ['Use `plan` for a concrete refactor preview.', 'Use `tests` for affected tests.', 'Use `check` after editing.'],
         benchmark: 'A08',
@@ -203,16 +203,16 @@ const COMMAND_CONTRACTS = Object.freeze({
         purpose: 'Preview rename or parameter-shape edits without mutating files.',
         target: 'Required symbol name or stable handle plus one refactor operation.',
         modes: [
-            { name: 'rename', when: '`renameTo` is supplied.', answer: 'Selected declaration plus indexed call/import/export edit previews.' },
+            { name: 'rename', when: '`renameTo` is supplied.', answer: 'Selected declaration plus indexed call/reference/import/export edit previews and source-text review items.' },
             { name: 'add parameter', when: '`addParam` is supplied.', answer: 'Selected declaration and call-site preview, optionally with a default.' },
             { name: 'remove parameter', when: '`removeParam` is supplied.', answer: 'Selected declaration and affected call-site preview.' },
         ],
         defaults: ['Preview only; no file writes.'],
-        truth: 'Changes are derived from indexed definitions/usages, include the selected declaration, and retain unverified/blocked or needs-review evidence separately.',
+        truth: 'Changes are derived from indexed definitions/usages, include the selected declaration, and retain unverified/blocked or needs-review evidence separately; non-source files receive an explicit exact-text search handoff.',
         nonGoals: ['Applying edits.', 'Guaranteeing the preview compiles.'],
         invalidCombinations: ['Exactly one of rename, add-parameter, or remove-parameter is required.', '`defaultValue` only applies to add-parameter.'],
         examples: ['ucn plan parseRequest --rename-to=parseIncoming', 'ucn plan parseRequest --add-param=context --default-value=null'],
-        jsonData: 'Before/after signatures, concrete declaration/call/import/export previews, changeSummary, needsReview markers, unverified sites, and account metadata.',
+        jsonData: 'Before/after signatures, concrete declaration/call/reference/import/export previews, changeSummary, reviewItems, non-source handoff, unverified sites, and account metadata.',
         output: 'Targeted refactor preview; inspect every unverified or warning entry.',
         next: ['Use `impact` before editing.', 'Use `check` and the compiler after applying the change manually.'],
         benchmark: 'A11',
@@ -245,14 +245,14 @@ const COMMAND_CONTRACTS = Object.freeze({
             { name: 'imports', when: '`direction=imports`.', answer: 'Downstream imported files.' },
             { name: 'importers', when: '`direction=importers`.', answer: 'Upstream importing files.' },
             { name: 'both', when: '`direction=both`.', answer: 'Both graph directions.' },
-            { name: 'cycles', when: '`cycles=true`.', answer: 'Detected static circular dependencies.' },
+            { name: 'cycles', when: '`cycles=true`.', answer: 'Detected static circular dependencies classified as eager or Python function-local/deferred.' },
         ],
         defaults: ['Direction defaults to both.', 'Traversal depth is bounded.'],
-        truth: 'Edges are resolved static import/include relationships inside the indexed project.',
+        truth: 'Edges are resolved static import/include relationships inside the indexed project; a deferred classification means at least one Python edge is function-local, not that runtime initialization can never trigger it.',
         nonGoals: ['Dynamic imports that cannot be resolved statically.', 'Package-manager or runtime dependency graphs.'],
         invalidCombinations: ['A file is required outside cycles mode.', 'Cycle mode does not combine with a file-direction question.'],
         examples: ['ucn deps src/server.ts --direction=both --depth=2', 'ucn deps --cycles'],
-        jsonData: 'Graph mode returns nodes/edges by direction; cycles mode returns cycle records.',
+        jsonData: 'Graph mode returns nodes/edges by direction; cycles mode returns classified cycle and deferred-edge records.',
         output: 'Broad graph output; use `depth=1`, one direction, or a file target.',
         next: ['Use `api` on a dependency boundary.', 'Use `show` on a symbol crossing the edge.'],
         benchmark: 'A12',
@@ -319,11 +319,11 @@ const COMMAND_CONTRACTS = Object.freeze({
             { name: 'candidates', when: 'Always; include flags can reveal protected categories.', answer: 'Static zero-usage candidates and usage count.' },
         ],
         defaults: ['Exported and decorated symbols excluded.', 'Tests excluded unless requested.'],
-        truth: 'A result means no modeled usage survived the command policy; known computed-dispatch registry members are withheld, and the result is explicitly not safe-delete proof.',
-        nonGoals: ['External consumers, reflection, generated registration, unresolved computed dispatch, or runtime reachability proof.'],
+        truth: 'A result means no modeled usage survived the command policy; known computed-dispatch registry members and statically named reflection targets are withheld, and the result is explicitly not safe-delete proof.',
+        nonGoals: ['External consumers, dynamically named reflection, generated registration, unresolved computed dispatch, or runtime reachability proof.'],
         invalidCombinations: [],
         examples: ['ucn deadcode --exclude=test', 'ucn deadcode --include-exported --limit=100'],
-        jsonData: 'Candidate records plus computed-dispatch/deletion-safety metadata and any registry members withheld from candidates.',
+        jsonData: 'Candidate records plus computed-dispatch, literal/dynamic-reflection, deletion-safety, and coverage metadata.',
         output: 'Broad candidate list; narrow by file/in/exclude/limit.',
         next: ['Review `usages`, `impact`, `entrypoints`, and `api`, then run compiler/tests before deletion.'],
         benchmark: 'A16',

package/core/deadcode.js

@@ -13,7 +13,7 @@ const { isTestFile } = require('./discovery');
 const { isFrameworkEntrypoint } = require('./entrypoints');
 const { splitParentList } = require('./graph-build');
 const { isOverrideMarked, codeUnitCompare, lineInRanges, maskBlockComments, escapeRegExp } = require('./shared');
-const { projectComputedDispatch } = require('./ast-analysis');
+const { projectComputedDispatch, reflectionSites } = require('./ast-analysis');
 
 const _CLASS_KINDS = ['class', 'struct', 'interface', 'trait', 'record'];
 
@@ -738,6 +738,34 @@ function deadcode(index, options = {}) {
             computedDispatchInfo.files.push(fe.relativePath);
         }
     }
+    const literalReflectionNames = new Set();
+    const reflectionInfo = {
+        count: 0,
+        literalCount: 0,
+        dynamicCount: 0,
+        fileCount: 0,
+        files: [],
+        names: [],
+    };
+    for (const [reflectionFile, fe] of index.files) {
+        if (!index.matchesFilters(fe.relativePath, options)) continue;
+        let sites = [];
+        try {
+            sites = reflectionSites(index._readFile(reflectionFile), fe.language);
+        } catch { /* coverage diagnostics own unreadable-file reporting */ }
+        if (sites.length === 0) continue;
+        reflectionInfo.count += sites.length;
+        reflectionInfo.literalCount += sites.filter(site => !site.dynamic).length;
+        reflectionInfo.dynamicCount += sites.filter(site => site.dynamic).length;
+        reflectionInfo.fileCount++;
+        if (reflectionInfo.files.length < 10) {
+            reflectionInfo.files.push(fe.relativePath);
+        }
+        for (const site of sites) {
+            if (site.name) literalReflectionNames.add(site.name);
+        }
+    }
+    reflectionInfo.names = [...literalReflectionNames].sort(codeUnitCompare);
 
     // Ensure callee index is built (lazy, reused across operations)
     if (!index.calleeIndex) {
@@ -810,8 +838,18 @@ function deadcode(index, options = {}) {
         potentiallyDeadNames = filteredNames;
     }
 
+    // A literal reflection target is a statically named runtime use. We may
+    // not know which same-name member receives it, so conservatively withdraw
+    // every deletion claim for that spelling rather than invent identity.
+    for (const reflectedName of literalReflectionNames) {
+        potentiallyDeadNames.delete(reflectedName);
+    }
+
     const coverage = scanDeadcodeCoverage(index, potentiallyDeadNames);
-    const coverageSuppressedNames = new Set(coverage.matchedNames);
+    const coverageSuppressedNames = new Set([
+        ...coverage.matchedNames,
+        ...literalReflectionNames,
+    ]);
     if (coverage.claimsWithdrawn) {
         // An unreadable file/directory can contain a use of any candidate.
         // Returning no deletion candidates is the only sound verdict.
@@ -1470,6 +1508,7 @@ function deadcode(index, options = {}) {
     results.excludedRuntimeContract = excludedRuntimeContract;
     results.excludedDynamicDispatch = excludedDynamicDispatch;
     results.computedDispatch = computedDispatchInfo;
+    results.reflection = reflectionInfo;
     results.coverage = {
         complete: coverage.complete,
         claimsWithdrawn: coverage.claimsWithdrawn,

package/core/execute.js

@@ -16,6 +16,7 @@ const { addTestExclusions, pickBestDefinition, parseSymbolHandle, looksLikeHandl
 const { cleanHtmlScriptTags, detectLanguage } = require('./parser');
 const { renderExpandItem } = require('./expand-cache');
 const { CANONICAL_COMMANDS } = require('./registry');
+const { isAccessorDefinition } = require('./accessors');
 
 // ============================================================================
 // HELPERS
@@ -1639,6 +1640,7 @@ const HANDLERS = {
             if (result.excludedDynamicDispatch != null) sliced.excludedDynamicDispatch = result.excludedDynamicDispatch;
             if (result.pythonImplicitExportFiles != null) sliced.pythonImplicitExportFiles = result.pythonImplicitExportFiles;
             if (result.computedDispatch != null) sliced.computedDispatch = result.computedDispatch;
+            if (result.reflection != null) sliced.reflection = result.reflection;
             if (result.coverage != null) sliced.coverage = result.coverage;
             // Truncation must be visible IN the JSON payload, not only in the
             // stderr note (fix #242) — the formatter reads this to emit
@@ -1875,7 +1877,8 @@ const HANDLERS = {
             const actualName = fnSplit ? fnSplit.methodName : fnName;
             const fnClassName = fnSplit ? fnSplit.className : p.className;
             let matches = index.find(actualName, { file: p.file, className: fnClassName, skipCounts: true })
-                .filter(m => m.type === 'function' || m.params !== undefined);
+                .filter(m => m.type === 'function' || m.params !== undefined ||
+                    isAccessorDefinition(m));
 
             // Line pin from a stable handle or explicit line= (fix #249:
             // `fn both.js:5:run` returned the OTHER same-name def — the

package/core/graph-build.js

@@ -451,6 +451,12 @@ function buildInheritanceGraph(index) {
                 }
                 index.extendsGraph.get(symbol.name).push({
                     file: filePath,
+                    // Per-def anchor (fix #300, attrs-measured): five
+                    // function-local `class C2Slots(...)` defs in one file
+                    // carry DIFFERENT parents — file-granular lookup returned
+                    // the first entry for all of them. startLine lets scope-
+                    // aware consumers pick the def the call site actually sees.
+                    startLine: symbol.startLine,
                     parents: resolvedParents
                 });
 

package/core/graph.js

@@ -48,7 +48,8 @@ function imports(index, filePath) {
                     resolved: null,
                     isExternal: false,
                     isDynamic: true,
-                    line
+                    line,
+                    deferred: !!imp.deferred,
                 };
             }
 
@@ -64,7 +65,8 @@ function imports(index, filePath) {
                     resolved: null,
                     isExternal: false,
                     isDynamic: true,
-                    line
+                    line,
+                    deferred: !!imp.deferred,
                 };
             }
 
@@ -94,7 +96,8 @@ function imports(index, filePath) {
                 // is still mechanically dynamic even when the path resolves —
                 // `type: 'dynamic'` with `isDynamic: false` was a contradiction.
                 isDynamic: imp.type === 'dynamic',
-                line
+                line,
+                deferred: !!imp.deferred,
             };
         });
     } catch (e) {
@@ -780,7 +783,37 @@ function circularDeps(index, options = {}) {
             }
         }
 
-        // Convert to relative paths and deduplicate
+        const importEdgeDetails = (fromFile, toFile) => {
+            const entry = index.files.get(fromFile);
+            if (!entry || entry.language !== 'python') return [];
+            const matches = [];
+            for (const detail of entry.importDetails || []) {
+                const specs = [detail.module];
+                const mod = String(detail.module || '');
+                for (const importedName of detail.names || []) {
+                    specs.push(mod.endsWith('.')
+                        ? mod + importedName
+                        : `${mod}.${importedName}`);
+                }
+                const reachesTarget = specs.some(spec => {
+                    const rel = entry.moduleResolved?.[spec];
+                    return rel && path.resolve(index.root, rel) === path.resolve(toFile);
+                });
+                if (!reachesTarget) continue;
+                matches.push({
+                    from: entry.relativePath,
+                    to: index.files.get(toFile)?.relativePath || path.relative(index.root, toFile),
+                    line: detail.line ?? null,
+                    deferred: !!detail.deferred,
+                });
+            }
+            return matches;
+        };
+
+        // Convert to relative paths, classify edge execution, and deduplicate.
+        // A cycle with at least one function-local Python import is still a
+        // structural dependency loop, but not an unconditional import-time
+        // loop. Preserve it as a deferred advisory rather than a false alarm.
         const seen = new Set();
         const uniqueCycles = [];
         for (const cycle of cycles) {
@@ -792,7 +825,37 @@ function circularDeps(index, options = {}) {
             const key = rotated.join('\0');
             if (!seen.has(key)) {
                 seen.add(key);
-                uniqueCycles.push({ files: rotated, length: rotated.length });
+                const rotatedAbs = [...cycle.slice(minIdx), ...cycle.slice(0, minIdx)];
+                const edges = [];
+                for (let edgeIndex = 0; edgeIndex < rotatedAbs.length; edgeIndex++) {
+                    const from = rotatedAbs[edgeIndex];
+                    const to = rotatedAbs[(edgeIndex + 1) % rotatedAbs.length];
+                    const details = importEdgeDetails(from, to);
+                    const deferred = details.length > 0 && details.every(detail => detail.deferred);
+                    edges.push({
+                        from: rotated[edgeIndex],
+                        to: rotated[(edgeIndex + 1) % rotated.length],
+                        deferred,
+                        ...(details.length > 0 && {
+                            lines: [...new Set(details.map(detail => detail.line)
+                                .filter(line => line != null))].sort((a, b) => a - b),
+                        }),
+                    });
+                }
+                const deferredEdges = edges.filter(edge => edge.deferred)
+                    .map(edge => ({
+                        from: edge.from,
+                        to: edge.to,
+                        line: edge.lines?.[0] ?? null,
+                        ...(edge.lines?.length > 1 && { lines: edge.lines }),
+                    }));
+                uniqueCycles.push({
+                    files: rotated,
+                    length: rotated.length,
+                    classification: deferredEdges.length > 0 ? 'deferred' : 'eager',
+                    edges,
+                    deferredEdges,
+                });
             }
         }
 
@@ -810,6 +873,8 @@ function circularDeps(index, options = {}) {
             if (targets && targets.size > 0) filesWithImports++;
         }
 
+        const eagerCycles = result.filter(cycle => cycle.classification !== 'deferred').length;
+        const deferredCycles = result.length - eagerCycles;
         return {
             cycles: result,
             totalFiles: index.files.size,
@@ -818,6 +883,8 @@ function circularDeps(index, options = {}) {
             summary: {
                 totalCycles: result.length,
                 filesInCycles: new Set(result.flatMap(c => c.files)).size,
+                eagerCycles,
+                deferredCycles,
             }
         };
     } finally {

package/core/index-ir.js

@@ -20,6 +20,7 @@ function createImportBindings(imports) {
                 ...(item.line != null && { line: item.line }),
                 ...(rename && { alias: rename.local }),
                 ...(item.defaultLike && { defaultLike: true }),
+                ...(item.deferred && { deferred: true }),
             };
         }));
 }
@@ -46,6 +47,15 @@ function createFileEntryFromIR({
         mtime,
         size,
         imports: imports.map(item => item.module),
+        ...(ir.language === 'python' && {
+            importDetails: imports.map(item => ({
+                module: item.module,
+                names: [...(item.names || [])],
+                ...(item.type && { type: item.type }),
+                ...(item.line != null && { line: item.line }),
+                ...(item.deferred && { deferred: true }),
+            })),
+        }),
         globalImports: imports.filter(item => item.global).map(item => item.module),
         importNames: imports.flatMap(item => item.names || []),
         importBindings: createImportBindings(imports),
@@ -66,7 +76,7 @@ function createFileEntryFromIR({
 
 const OPTIONAL_SYMBOL_FIELDS = Object.freeze([
     'returnedFunctionResult', 'isFunctionVariable', 'paramTypes', 'isAsync',
-    'isGenerator', 'generics', 'extends', 'implements', 'indent', 'isNested',
+    'isGenerator', 'generics', 'genericBounds', 'extends', 'implements', 'indent', 'isNested',
     'enclosingType', 'isMethod', 'receiver', 'memberType', 'fieldType',
     'aliasOf', 'derefTarget', 'decorators', 'decoratorsWithArgs',
     'annotationsWithArgs', 'attributesWithArgs', 'nameLine', 'traitImpl',
@@ -76,8 +86,9 @@ const OPTIONAL_SYMBOL_FIELDS = Object.freeze([
     'lexicalScopeStartLine', 'lexicalScopeEndLine',
     'returnTypeQualifier', 'macroNeverReturns', 'callbackParamTypes', 'iteratorItemType',
     'returnedConcreteType', 'returnedConstructors', 'templateDependent',
+    'isSpecialization',
     'linkage', 'functionLike', 'callableAlias', 'exportedAlias',
-    'aliasOwner', 'aliasMember',
+    'aliasOwner', 'aliasMember', 'macroParamEffects',
 ]);
 
 function materializeSymbol(fileEntry, item) {

package/core/ir.js

@@ -43,7 +43,7 @@ function normalizeSymbol(symbol, family, language, kind, owner = null) {
     };
     const passthrough = [
         'docstring', 'returnedFunctionResult', 'isFunctionVariable', 'paramTypes',
-        'isAsync', 'isGenerator', 'generics', 'extends', 'implements', 'indent',
+        'isAsync', 'isGenerator', 'generics', 'genericBounds', 'extends', 'implements', 'indent',
         'isNested', 'enclosingType', 'isMethod', 'memberType', 'fieldType',
         'aliasOf', 'derefTarget', 'decorators', 'decoratorsWithArgs',
         'annotationsWithArgs', 'attributesWithArgs', 'nameLine', 'traitImpl',
@@ -53,8 +53,9 @@ function normalizeSymbol(symbol, family, language, kind, owner = null) {
         'namespace', 'lexicalScopeStartLine', 'lexicalScopeEndLine',
         'returnTypeQualifier', 'macroNeverReturns', 'callbackParamTypes', 'iteratorItemType',
         'returnedConcreteType', 'returnedConstructors', 'templateDependent',
+        'isSpecialization',
         'linkage', 'functionLike', 'callableAlias', 'exportedAlias',
-        'aliasOwner', 'aliasMember',
+        'aliasOwner', 'aliasMember', 'macroParamEffects',
     ];
     for (const field of passthrough) {
         if (symbol[field] !== undefined && symbol[field] !== null) {
@@ -107,7 +108,8 @@ function createFileIR({
                 }),
             };
             append(inherited,
-                inherited.memberType === 'field' ? 'state' : 'callable',
+                ['field', 'property'].includes(inherited.memberType)
+                    ? 'state' : 'callable',
                 inherited.memberType || (inherited.isConstructor ? 'constructor' : 'method'),
                 type.name);
         }

package/core/output/analysis.js

@@ -786,12 +786,17 @@ function formatImpact(impact, options = {}) {
     // Summary (confirmed + unverified tiers reported separately)
     const impactUnverified = impact.unverifiedSites || [];
     const unverifiedSuffix = impactUnverified.length > 0 ? ` confirmed + ${impactUnverified.length} unverified` : '';
+    if (impact.propertyAccesses) {
+        const pa = impact.propertyAccesses;
+        const uv = pa.unverifiedCount ? ` + ${pa.unverifiedCount} unverified` : '';
+        lines.push(`DEPENDENCY SITES: ${impact.totalDependencySites} confirmed${uv}`);
+    }
     if (impact.shownCallSites !== undefined && impact.shownCallSites < impact.totalCallSites) {
         lines.push(`CALL SITES: ${impact.shownCallSites} shown of ${impact.totalCallSites}${unverifiedSuffix ? ` total${unverifiedSuffix}` : ' total'}`);
     } else {
         lines.push(`CALL SITES: ${impact.totalCallSites}${unverifiedSuffix}`);
     }
-    lines.push(`  Files affected: ${impact.byFile.length}`);
+    lines.push(`  Files affected: ${impact.affectedFiles ?? impact.byFile.length}`);
 
     // Patterns
     // BUG-1: also surface structural classification counts (inLoop / inTry /
@@ -856,6 +861,30 @@ function formatImpact(impact, options = {}) {
     }
     if (impactReach.note && !compact) lines.push(impactReach.note);
 
+    if (impact.propertyAccesses) {
+        const access = impact.propertyAccesses;
+        lines.push(`${compact ? '' : '\n'}PROPERTY ACCESS SITES: ${access.confirmedCount} confirmed` +
+            (access.unverifiedCount ? ` + ${access.unverifiedCount} unverified` : ''));
+        for (const group of access.byFile) {
+            for (const site of group.sites) {
+                const caller = site.callerName ? ` [${site.callerName}]` : '';
+                const expr = site.expression ? `: ${site.expression.replace(/\s+/g, ' ').slice(0, 100)}` : '';
+                lines.push(`  ${group.file}:${site.line}${caller}${expr}`);
+            }
+        }
+        if (access.unverifiedSites.length > 0) {
+            lines.push(`${compact ? '' : '\n'}UNVERIFIED PROPERTY ACCESS CANDIDATES (${access.unverifiedSites.length}) — matching attribute syntax, receiver identity unresolved:`);
+            for (const site of access.unverifiedSites.slice(0, 10)) {
+                const caller = site.callerName ? ` [${site.callerName}]` : '';
+                const expr = site.expression ? `: ${site.expression.replace(/\s+/g, ' ').slice(0, 100)}` : '';
+                lines.push(`  ${site.file}:${site.line}${caller}${expr}`);
+            }
+            if (access.unverifiedSites.length > 10) {
+                lines.push(`  (+${access.unverifiedSites.length - 10} more unverified)`);
+            }
+        }
+    }
+
     // Unverified tier: visible, capped at 10 one-liners
     if (impactUnverified.length > 0) {
         lines.push(`${compact ? '' : '\n'}UNVERIFIED CALL SITES (${impactUnverified.length}) — call syntax, no binding/receiver evidence:`);

package/core/output/graph.js

@@ -21,7 +21,7 @@ function formatImports(imports, filePath) {
     if (internal.length > 0) {
         lines.push('INTERNAL:');
         for (const imp of internal) {
-            lines.push(`  ${imp.module}`);
+            lines.push(`  ${imp.module}${imp.deferred ? ' [function-local/deferred]' : ''}`);
             if (imp.resolved) {
                 lines.push(`    -> ${imp.resolved}${imp.indexed === false
                     ? ' (not indexed; absent from dependency graph)'
@@ -37,7 +37,7 @@ function formatImports(imports, filePath) {
         if (internal.length > 0) lines.push('');
         lines.push('EXTERNAL:');
         for (const imp of external) {
-            lines.push(`  ${imp.module}`);
+            lines.push(`  ${imp.module}${imp.deferred ? ' [function-local/deferred]' : ''}`);
             if (imp.names && imp.names.length > 0) {
                 lines.push(`    ${imp.names.join(', ')}`);
             }
@@ -48,7 +48,7 @@ function formatImports(imports, filePath) {
         if (internal.length > 0 || external.length > 0) lines.push('');
         lines.push('DYNAMIC (unresolved):');
         for (const imp of dynamic) {
-            lines.push(`  ${imp.module || '(variable)'}`);
+            lines.push(`  ${imp.module || '(variable)'}${imp.deferred ? ' [function-local/deferred]' : ''}`);
             if (imp.names && imp.names.length > 0) {
                 lines.push(`    ${imp.names.join(', ')}`);
             }
@@ -77,6 +77,7 @@ function formatImportsJson(imports, filePath) {
             resolved: i.resolved || null,
             indexed: i.resolved ? i.indexed !== false : false,
             isDynamic: !!i.isDynamic,
+            deferred: !!i.deferred,
             line: i.line ?? null
         }))
     }, null, 2);
@@ -426,16 +427,35 @@ function formatCircularDeps(result) {
         return lines.join('\n');
     }
 
-    for (let i = 0; i < result.cycles.length; i++) {
-        const cycle = result.cycles[i];
+    const eager = result.cycles.filter(cycle => cycle.classification !== 'deferred');
+    const deferred = result.cycles.filter(cycle => cycle.classification === 'deferred');
+    let cycleNumber = 0;
+    const renderGroup = (title, group, deferredGroup = false) => {
+        if (group.length === 0) return;
         lines.push('');
-        lines.push(`Cycle ${i + 1} (${cycle.length} files):`);
-        lines.push(`  ${cycle.files.join(' → ')} → ${cycle.files[0]}`);
-    }
+        lines.push(`${title} (${group.length}):`);
+        for (const cycle of group) {
+            cycleNumber++;
+            lines.push('');
+            lines.push(`Cycle ${cycleNumber} (${cycle.length} files):`);
+            lines.push(`  ${cycle.files.join(' → ')} → ${cycle.files[0]}`);
+            if (deferredGroup) {
+                for (const edge of cycle.deferredEdges || []) {
+                    const at = edge.line != null ? `:${edge.line}` : '';
+                    lines.push(`  deferred edge: ${edge.from}${at} → ${edge.to} (function-local import)`);
+                }
+            }
+        }
+    };
+    renderGroup('IMPORT-TIME CYCLES', eager);
+    renderGroup('DEFERRED CYCLES', deferred, true);
 
     lines.push('');
     const { totalCycles, filesInCycles } = result.summary;
     lines.push(`Summary: ${totalCycles} circular dependency chain${totalCycles !== 1 ? 's' : ''} involving ${filesInCycles} file${filesInCycles !== 1 ? 's' : ''} (${scannedCount} files with imports scanned).`);
+    if (deferred.length > 0) {
+        lines.push(`${deferred.length} chain${deferred.length === 1 ? '' : 's'} contain a function-local import; they are not unconditional import-time cycles, but may still matter if invoked during initialization.`);
+    }
 
     return lines.join('\n');
 }

package/core/output/public.js

@@ -384,6 +384,10 @@ function formatPublicJson(command, result, params = {}, execution = {}) {
         commandMeta.pythonImplicitExportFiles = result.pythonImplicitExportFiles || 0;
         commandMeta.excludedDynamicDispatch = result.excludedDynamicDispatch || 0;
         commandMeta.computedDispatch = result.computedDispatch || { count: 0, names: [] };
+        commandMeta.reflection = result.reflection || {
+            count: 0, literalCount: 0, dynamicCount: 0,
+            fileCount: 0, files: [], names: [],
+        };
         if (result.coverage) commandMeta.coverage = result.coverage;
         if (result.limitInfo) {
             commandMeta.total = result.limitInfo.total;

package/core/output/refactoring.js

@@ -70,7 +70,7 @@ function formatPlan(plan, options = {}) {
     lines.push(`  Files affected: ${plan.filesAffected}`);
     if (plan.changeSummary) {
         const summary = plan.changeSummary;
-        lines.push(`  Definition ${summary.definitions}, calls/references ${summary.calls}, imports ${summary.imports}, exports ${summary.exports}; manual review required for ${summary.reviewRequired} of these changes`);
+        lines.push(`  Definition ${summary.definitions}, calls ${summary.calls}, references ${summary.references || 0}, text dependencies ${summary.textReferences || 0}, imports ${summary.imports}, exports ${summary.exports}; manual review items ${summary.reviewRequired}`);
     }
     if (plan.unchangedSites > 0) {
         lines.push(`  ${plan.unchangedSites} existing call site${plan.unchangedSites === 1 ? '' : 's'} require no edit because the new parameter has a default.`);
@@ -78,6 +78,9 @@ function formatPlan(plan, options = {}) {
     if (plan.scopeWarning) {
         lines.push(`  Note: ${plan.scopeWarning.hint}`);
     }
+    if (plan.outsideIndexedSource) {
+        lines.push(`  Source boundary: ${plan.outsideIndexedSource.action}`);
+    }
     lines.push('');
 
     // Group by file
@@ -101,6 +104,17 @@ function formatPlan(plan, options = {}) {
         }
     }
 
+    if (plan.reviewItems?.length > 0) {
+        lines.push(`\nREVIEW ITEMS (${plan.reviewItems.length}) — source text dependencies are never rewritten automatically:`);
+        for (const item of plan.reviewItems.slice(0, 20)) {
+            lines.push(`  ${item.file}:${item.line}: ${item.expression.replace(/\s+/g, ' ').slice(0, 120)}`);
+            lines.push(`    → ${item.suggestion}`);
+        }
+        if (plan.reviewItems.length > 20) {
+            lines.push(`  (+${plan.reviewItems.length - 20} more review items)`);
+        }
+    }
+
     // v4 tiered contract: candidates without evidence are not planned but
     // stay visible — a rename that misses one of these breaks at runtime.
     lines.push(..._unverifiedBandLines(plan.unverifiedSites));
@@ -139,7 +153,8 @@ function formatPlanJson(plan) {
     // commands still emitting a bare result object).
     return JSON.stringify({
         meta: {
-            complete: (plan.unverifiedCount || 0) === 0,
+            complete: (plan.unverifiedCount || 0) === 0 &&
+                (plan.changeSummary?.reviewRequired || 0) === 0,
             unverified: plan.unverifiedCount || 0,
             ...(plan.account && { account: plan.account }),
             ...(plan.warnings?.length > 0 && { warnings: plan.warnings }),
@@ -153,8 +168,12 @@ function formatPlanJson(plan) {
             before: { signature: plan.before.signature },
             after: { signature: plan.after.signature },
             totalChanges: plan.totalChanges,
+            totalReviewItems: plan.totalReviewItems || 0,
             filesAffected: plan.filesAffected,
             ...(plan.changeSummary && { changeSummary: plan.changeSummary }),
+            ...(plan.outsideIndexedSource && {
+                outsideIndexedSource: plan.outsideIndexedSource,
+            }),
             ...(plan.unchangedSites > 0 && { unchangedSites: plan.unchangedSites }),
             changes: plan.changes.map(c => ({
                 file: c.file,
@@ -167,6 +186,16 @@ function formatPlanJson(plan) {
                 ...(c.isImport && { isImport: true }),
                 ...(c.isExport && { isExport: true }),
                 ...(c.needsReview && { needsReview: true }),
+                ...(c.textDependency && { textDependency: true }),
+            })),
+            reviewItems: (plan.reviewItems || []).map(item => ({
+                file: item.file,
+                line: item.line,
+                expression: item.expression,
+                suggestion: item.suggestion,
+                editKind: item.editKind,
+                needsReview: true,
+                textDependency: true,
             })),
             // v4 tiered contract passthrough
             unverifiedCount: plan.unverifiedCount,

package/core/output/reporting.js

@@ -294,6 +294,12 @@ function formatDeadcode(results, options = {}) {
     if (results.computedDispatch?.count > 0) {
         lines.push(`\nWARNING: ${results.computedDispatch.count} computed dispatch call(s) in ${results.computedDispatch.fileCount} file(s). Dead-code results are review candidates; runtime-selected members may not have a named static edge.`);
     }
+    if (results.reflection?.literalCount > 0) {
+        lines.push(`\n${results.reflection.literalCount} literal reflection use(s) name ${results.reflection.names.length} member spelling(s); matching symbols were withheld from deletion candidates.`);
+    }
+    if (results.reflection?.dynamicCount > 0) {
+        lines.push(`\nWARNING: ${results.reflection.dynamicCount} dynamic reflection use(s) have no static member spelling. Dead-code results remain review candidates because runtime-selected members cannot be attributed.`);
+    }
     if (results.coverage?.complete === false) {
         const c = results.coverage;
         const reasonText = Object.entries(c.reasons || {})
@@ -337,6 +343,7 @@ function formatDeadcodeJson(results) {
             ...(results.pythonImplicitExportFiles > 0 && { pythonImplicitExportFiles: results.pythonImplicitExportFiles }),
             ...(results.excludedDynamicDispatch > 0 && { excludedDynamicDispatch: results.excludedDynamicDispatch }),
             ...(results.computedDispatch?.count > 0 && { computedDispatch: results.computedDispatch }),
+            ...(results.reflection?.count > 0 && { reflection: results.reflection }),
             ...(results.coverage?.complete === false && { coverage: results.coverage }),
             symbols: results.map(item => {
                 const handleSym = { ...item, relativePath: item.relativePath || item.file };