docs(10.2-01): summarize modules migration

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

@@ -0,0 +1,118 @@
+---
+phase: 10.2-nest-framework-packages-under-modules-and-write-run-docs
+plan: "01"
+subsystem: framework-layout
+tags: [go, modules, imports, monorepo, migration]
+
+requires:
+  - phase: 10-admin-vue-spa
+    provides: complete framework and Fonoteka consumers before the package-layout migration
+provides:
+  - 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
+affects: [10.2-02, 11]
+
+actuals:
+  tasks: 3
+  commits: 7
+plan_head_before: a9a7bbef73e7e61b01796d9803c06367ab06c34b
+plan_head_after: 57e7b56983d2cb4032fbf44aa6bcc433d4dab96c
+app_plan_head_before: 21c0f12
+app_plan_head_after: e8b22d3078b7811fb736c45866c71813fc10c5e4
+
+tech-stack:
+  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
+
+key-files:
+  created:
+    - modules/
+  modified:
+    - 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/**
+
+key-decisions:
+  - "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."
+
+requirements-completed: []
+
+coverage:
+  - id: D-01-D-06
+    description: "All framework packages are nested, all controlled consumers resolve the new imports, and both repositories remain green."
+    verification:
+      - kind: unit
+        ref: "go vet ./... && go test ./..."
+        status: pass
+      - kind: integration
+        ref: "go vet/go test for examples/hello plus base, greeter, and optional nested modules"
+        status: pass
+      - kind: integration
+        ref: "go vet/go test in ../fonoteka.go including both plugin modules"
+        status: pass
+    human_judgment: false
+
+completed: 2026-09-28
+status: 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.