---
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.