declscope makes an unexported Go helper private to the namespace that declared it

Counting what the linter adds, a flat package gets three levels of visibility: exported, unexported, and private to a namespace ^[18]. The first two come from the language, which has exactly two and no file scope ^[1].

Both files in the worked example sit in package `database` ^[12]. The compiler takes the cross-file call without complaint, because it is a call to an unexported function in the same package ^[15]. declscope runs as a separate pass over the package and prints the crossing at both ends, the declaration at `user_repository.go:21:6` and then the use: `order_repository.go:21:20: used here, in namespace "orderRepository"` ^[16][17].

The flat school has reasons for putting itself in this position. Split a package to get a boundary and you take on import cycles, plus the interfaces you write only to invert a dependency and break them ^[4]. Every name the two halves share has to be exported, so a boundary between two files becomes a published API unless you add an `internal/` layer at each boundary you draw ^[5]. A wrong boundary is expensive too: moving a declaration between files disturbs little, while moving it between packages tends to break every importer ^[6]. Stay flat and the smallest helper is a package-wide name, and any field can be written from anywhere in the package ^[2].

So the ownership rule migrates into the identifiers. Both helpers in the example pack a raw result set into a domain entity, both want to be called `scan`, and a flat package can declare only one `scan`, so they are written apart by hand as `scanUser` and `scanOrder` ^[13]. The `User` and `Order` state which repository each helper belongs to ^[14]. `normalizeEmail` was written in `user_repository.go` for `scanUser`, and `scanOrder` calls it anyway ^[15].

An agent finds an unexported helper in scope and calls it, or sees an unexported field and writes to it. Both compile, and a quick review lets them through ^[10]. mpyw wrote that he put the convention in CLAUDE.md and could not make it hold ^[9]. "A convention in natural language cannot be checked deterministically, so it can only ever work probabilistically," he wrote ^[8]. The stated design goal is that a crossing tells the agent what it crossed and how to repair it, and the next agent reads that decision ^[19].

Whether the result transfers depends on how a namespace gets declared. The published evidence is one two-file example built to show the failure ^[12]. In a package of eighty files, the boundaries have to be written somewhere a reviewer can audit and a newcomer can find, and the post does not show how a namespace is declared ^[11][20].

In my view this is the right trade in packages an agent edits, because the review that would have caught the crossing is the review being skipped ^[10]. In a package only people touch, the comment has mostly held, and the convention was already legible in the names ^[14].