summercms/.planning/phases/10.2-nest-framework-packages-under-modules-and-write-run-docs/10.2-01-SUMMARY.md

phase, plan, subsystem, tags, requires, provides, affects, actuals, plan_head_before, plan_head_after, app_plan_head_before, app_plan_head_after, tech-stack, key-files, key-decisions, requirements-completed, coverage, completed, status

phase	plan	subsystem	tags	requires	provides	affects	actuals	plan_head_before	plan_head_after	app_plan_head_before	app_plan_head_after	tech-stack	key-files	key-decisions	requirements-completed	coverage	completed	status
10.2-nest-framework-packages-under-modules-and-write-run-docs	01	framework-layout	go modules imports monorepo migration	phase provides 10-admin-vue-spa complete framework and Fonoteka consumers before the package-layout migration	all 18 beach-named framework packages nested under modules/ with package names unchanged nested import paths across summercms.go, examples/hello, and fonoteka.go retargeted build stubs, validation scripts, Vite output, and repository-relative tests green vet and test matrix for both repositories and all nested Go modules	10.2-02 11	tasks commits 3 7	a9a7bbef73	57e7b56983	21c0f12	e8b22d3078b7811fb736c45866c71813fc10c5e4	added patterns Framework libraries live at modules/<package> while retaining their existing Go package names Historical planning evidence remains immutable; executable audits translate historical package columns to the current modules/ layout Nested-module examples are vetted and compiled explicitly because root ./... does not traverse them	created modified modules/ cmd/summer/** internal/build/** examples/hello/** scripts/check-phase*.sh scripts/check-admin-*.sh admin/vite.config.ts ../fonoteka.go/app/** ../fonoteka.go/parity/** ../fonoteka.go/plugins/**	Kept the migration as one tracer task plus one bulk task: the change is mechanically broad but one atomic import-graph rewrite. Kept one root go.mod and the existing go.work entries; modules/ is an organizational directory, not a Go multi-module boundary. Updated the Fonoteka parity audit instead of rewriting historical Phase 08 evidence.		id description verification human_judgment D-01-D-06 All framework packages are nested, all controlled consumers resolve the new imports, and both repositories remain green. kind ref status unit go vet ./... && go test ./... pass kind ref status integration go vet/go test for examples/hello plus base, greeter, and optional nested modules pass kind ref status integration go vet/go test in ../fonoteka.go including both plugin modules pass false	2026-09-28	complete

Phase 10.2 Plan 01: Nest framework packages under modules Summary

All 18 framework packages now live under modules/; every controlled importer and path-sensitive tool follows the new layout, and the complete two-repository Go validation matrix passes.

Accomplishments

• Proved the migration with festival, including its framework, example, and Fonoteka importers.
• Moved the remaining 17 packages with history-preserving renames and retained all existing Go package names.
• Rewrote imports across the framework, generator templates, nested examples, and 125 Fonoteka consumer files.
• Retargeted admin output, OpenAPI/dist checks, phase gates, fixture paths, and source-audit paths that depended on the old repository-relative layout.
• Verified the root framework module, all four examples/hello module contexts, the Fonoteka root, and both Fonoteka plugin modules with go vet and go test.

Task Commits

1. Task 1: festival tracer. ac1f6d1 (summercms.go), 32bd982 (fonoteka.go)
2. Task 2: remaining packages and all importers/path literals. 5e50b16 (summercms.go), 03a417a (fonoteka.go)
3. Task 3: full validation and phase-caused fixture/audit fixes. 57e7b56 (summercms.go), e8b22d3 (fonoteka.go)

Plan metadata: committed separately with this summary.

Decisions Made

• The two-plan lean structure was retained. Splitting a single import-graph rewrite by arbitrary file count would have introduced broken intermediate states or temporary compatibility scaffolding.
• No package aliases, forwarding packages, new go.mod files, or dependency changes were introduced.
• Historical .planning/phases/** paths were left unchanged. The live Fonoteka audit maps their summercms.go package column into the current modules/ directory.

Deviations from Plan

Auto-fixed issues

1. Five moved tests retained repository-relative paths. Two CLI parity tests still referenced root tide, two cabana tests resolved root admin/ from one directory too shallow, and phrasebook did the same. Their path calculations were updated after the first full test pass exposed them.
2. Fonoteka's historical PHP-test-map audit interpreted wristband as a current root directory. The audit now prefixes framework package rows with modules/, preserving the historical Phase 08 document exactly as required.
3. Sandbox-only validation failures. Localhost listeners and the default Go build cache were unavailable inside the restricted sandbox. The identical validation command was rerun outside it; the command then exposed the real stale audit path above and passed after that fix.

Verification

• go vet ./... && go test ./... in summercms.go: pass
• Explicit vet and compile-only test across examples/hello, base, greeter, and optional: pass
• go vet and go test in fonoteka.go including both plugin modules: pass
• No root beach-package directories or per-package go.mod files remain.

Self-Check: PASSED

• Root commits present: ac1f6d1, 5e50b16, 57e7b56
• Fonoteka commits present: 32bd982, 03a417a, e8b22d3
• modules/festival, modules/compass, and modules/boardwalk/dist exist.
• Full declared Task 3 validation exits 0.