carlos / platform Public

framework design doc: record §4 package-per-directory resolution (#21)

rastrillo's generator hit a real gap the routing example glossed over
(two Handle-declaring files, one directory, one Go package) and
resolved it during implementation; fold that decision back into the
design doc rather than leaving it undocumented outside the code.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Paul Campbell 2 months ago a8b4ad479e6a3263cf31faa382a779f7d2b15231 parent b60b18a

1 file changed, +20 −0

docs/superpowers/specs/2026-08-01-carlos-framework-design.md +20 −0

diff --git a/docs/superpowers/specs/2026-08-01-carlos-framework-design.md b/docs/superpowers/specs/2026-08-01-carlos-framework-design.md

index dba29cc28..8524df33e 100644

--- a/docs/superpowers/specs/2026-08-01-carlos-framework-design.md

+++ b/docs/superpowers/specs/2026-08-01-carlos-framework-design.md

@@ -218,6 +218,19 @@ six apps already hand-builds (`mux.HandleFunc("GET /{slug}/orders/{token}",

...)`), just wired by directory walk instead of by hand. **Build fails

loudly on any collision** between a hand-written and a generated path.

+**Package-per-directory (implementation, 2026-08-03).** The example above

+puts `cancel.POST.go` and `edit.GET.go` in the same directory, but Go

+compiles one package per directory — both files declaring a bare `func

+Handle` would collide if compiled in place. `rastrillo`'s generator

+(`internal/generate/generate.go`) resolves this by never compiling

+`actions/` in place: each file is parsed, its package clause rewritten to

+a name unique to its route, and the result written into its own directory

+under `gen/actions/`, which `gen/router.go` imports normally — no AST

+surgery beyond the package clause. A leaner alternative, lifting just the

+`Handle` function via full AST extraction to stay closer to "one file, no

+package boilerplate," was deliberately deferred rather than rushed: real

+complexity for a cosmetic win.

**Action signature**, fixed early per the recovered spec's own advice

("decide once, painful to change"):

@@ -867,3 +880,10 @@ confirmed rather than assumed (§11); no skill-version pinning in v1

questions — TOML library choice, the mergeable ordering default, and the

EXECUTOR declaration mechanism — came back "don't know"/"maybe" and are

carried into §15 genuinely open, not guessed at.

+A seventh pass (2026-08-03) folded back an implementation gap §4's

+routing example glossed over: `carlosframework/rastrillo`'s generator

+found the one-package-per-directory collision the example invites, and

+resolved it (package-clause rewrite, one generated package per route

+under `gen/actions/`) rather than redesigning the convention — recorded

+in §4 as a package-per-directory note.