Phillip Wood [off-list ref] writes:

As I said last time this came up, I don't really buy the discoverability 
argument because there are just as many files to trawl through to find 
what you're looking through and now there is an extra directory to 
check. I think the solution to that is to recommend folks use "git grep" 
or ctags etc. not moving code to a new directory.

Hear, hear.  Also it would be great if we can trick some talented
technical writer into writing the "map" of the source so that by
reading this one or two pager, any new person with reasonable
competence will know how things are partitioned into pieces and how
these pieces fit together.  I wonder how good LLMs are these days?
;-)

I do however think putting all the library code in a subdirectory makes 
it easier to say things like "please try to avoid new uses of 
'the_repository' and prefer 'error()' over 'die()' in library code" 
because all the library code is in the same directory. I think that is a 
much stronger selling point.

Yes.  "library code (things outside the subdirectories) should not
use X" would work just fine, though.

Another cost is remembering things have moved - the other day I spent 
too long wondering why "git show origin/seen:wt-status.c" wasn't working 
until I ran "git log origin/seen" and realized it had move to 
lib/wt-status.c.

Yes, this has bit me multiple dozen times, as the tip of 'seen' is
contaminated with this rename, already.  It is a huge pain.