Finalize import discovery documentation and audits

internal/engine/import_selection.go

@@ -97,6 +97,9 @@ func selectDirectoryImportCandidates(access *filesystemAccess, basePath string,
 	}
 	discovered := make([]selectedImportCandidate, 0)
 	seenCandidates := make(map[string]struct{})
+	// Each root is traversed once. Filename patterns are tested together for
+	// every discovered file, and seenCandidates forms their set union across
+	// overlapping roots. Exclusions are applied once below as set difference.
 	for _, root := range roots {
 		missing, isDirectory, diagnostic := validateNamedImportTarget(access, root, false, true)
 		if diagnostic != nil {
@@ -121,6 +124,8 @@ func selectDirectoryImportCandidates(access *filesystemAccess, basePath string,
 			continue
 		}
 		stack := []importDirectoryFrame{{directory: root, depth: 0, entries: entries, identity: rootTarget.identity}}
+		// Active-path cycle detection removes each directory when its frame is
+		// popped, so a later non-active alias remains a separate traversal.
 		activeDirectories := map[string]struct{}{rootTarget.identity: {}}
 		for len(stack) != 0 {
 			frameIndex := len(stack) - 1