golem15/summercms
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cc584e906e2a67f7e04b979ac632d6e24c21011d
summercms/.planning/phases/10.2-nest-framework-packages-under-modules-and-write-run-docs/10.2-VERIFICATION.md
Jakub Zych cc584e906e docs(phase-10.2): complete phase execution
2026-09-28 14:13:20 +02:00

420 lines
20 KiB
Markdown
Raw Blame History

---
phase: 10.2-nest-framework-packages-under-modules-and-write-run-docs
verified: 2026-09-28T12:11:41Z
status: passed
score: 7/7 must-haves verified
covered_files:
- ".planning/phases/10.2-nest-framework-packages-under-modules-and-write-run-docs/10.2-01-PLAN.md"
- ".planning/phases/10.2-nest-framework-packages-under-modules-and-write-run-docs/10.2-01-SUMMARY.md"
- ".planning/phases/10.2-nest-framework-packages-under-modules-and-write-run-docs/10.2-02-PLAN.md"
- ".planning/phases/10.2-nest-framework-packages-under-modules-and-write-run-docs/10.2-02-SUMMARY.md"
- "README.md"
- "admin/vite.config.ts"
- "cmd/summer/main.go"
- "cmd/summer/main_test.go"
- "cmd/summer/parity.go"
- "cmd/summer/parity_contract_test.go"
- "cmd/summer/parity_test.go"
- "cmd/summer/runtime.go"
- "examples/hello/hello_test.go"
- "examples/hello/main.go"
- "examples/hello/plugins/base/plugin.go"
- "examples/hello/plugins/greeter/plugin.go"
- "examples/hello/plugins/greeter/plugin_test.go"
- "examples/hello/plugins/optional/plugin.go"
- "internal/build/build.go"
- "internal/build/build_test.go"
- "internal/build/stubs/artifacts.tmpl"
- "internal/build/stubs/plugin.tmpl"
- "internal/build/stubs/registry.tmpl"
- "modules/backpack/README.md"
- "modules/backpack/app.go"
- "modules/backpack/app_test.go"
- "modules/backpack/services.go"
- "modules/backpack/services_test.go"
- "modules/boardwalk/README.md"
- "modules/boardwalk/boardwalk.go"
- "modules/boardwalk/boardwalk_test.go"
- "modules/boardwalk/dist/assets/dm-mono-latin-400-normal--0xN8mdc.woff"
- "modules/boardwalk/dist/assets/dm-mono-latin-400-normal-4GdczIuU.woff2"
- "modules/boardwalk/dist/assets/dm-mono-latin-500-normal-CN8Miw6E.woff"
- "modules/boardwalk/dist/assets/dm-mono-latin-500-normal-DRMDZjhP.woff2"
- "modules/boardwalk/dist/assets/dm-mono-latin-ext-400-normal-1aZr6b2b.woff"
- "modules/boardwalk/dist/assets/dm-mono-latin-ext-400-normal-C2zvOubV.woff2"
- "modules/boardwalk/dist/assets/dm-mono-latin-ext-500-normal-BtRyHRi6.woff2"
- "modules/boardwalk/dist/assets/dm-mono-latin-ext-500-normal-Dw3M13d8.woff"
- "modules/boardwalk/dist/assets/dm-sans-latin-400-normal-BwCSEQnW.woff"
- "modules/boardwalk/dist/assets/dm-sans-latin-400-normal-CW0RaeGs.woff2"
- "modules/boardwalk/dist/assets/dm-sans-latin-500-normal-B9HHJjqV.woff2"
- "modules/boardwalk/dist/assets/dm-sans-latin-500-normal-Dr3UlScf.woff"
- "modules/boardwalk/dist/assets/dm-sans-latin-600-normal-Aqo67rzb.woff2"
- "modules/boardwalk/dist/assets/dm-sans-latin-600-normal-BmdmIIQ2.woff"
- "modules/boardwalk/dist/assets/dm-sans-latin-700-normal-CUSSCpQX.woff"
- "modules/boardwalk/dist/assets/dm-sans-latin-700-normal-DvUfVpUG.woff2"
- "modules/boardwalk/dist/assets/dm-sans-latin-ext-400-normal-BjWJ59Pq.woff"
- "modules/boardwalk/dist/assets/dm-sans-latin-ext-400-normal-BtiwyxMk.woff2"
- "modules/boardwalk/dist/assets/dm-sans-latin-ext-500-normal-BJfUCQsA.woff2"
- "modules/boardwalk/dist/assets/dm-sans-latin-ext-500-normal-DR84L5F-.woff"
- "modules/boardwalk/dist/assets/dm-sans-latin-ext-600-normal-4vooXBpG.woff2"
- "modules/boardwalk/dist/assets/dm-sans-latin-ext-600-normal-DRtaDpgU.woff"
- "modules/boardwalk/dist/assets/dm-sans-latin-ext-700-normal-BLI3TTWz.woff"
- "modules/boardwalk/dist/assets/dm-sans-latin-ext-700-normal-CJIcxD6K.woff2"
- "modules/boardwalk/dist/assets/index-BAlwlQ8W.js"
- "modules/boardwalk/dist/assets/index-CLf0gZ3D.css"
- "modules/boardwalk/dist/index.html"
- "modules/bonfire/README.md"
- "modules/bonfire/command.go"
- "modules/bonfire/command_test.go"
- "modules/bonfire/output.go"
- "modules/bonfire/output_test.go"
- "modules/bonfire/prompts.go"
- "modules/bonfire/prompts_test.go"
- "modules/bonfire/root.go"
- "modules/bonfire/widgets.go"
- "modules/bouncer/README.md"
- "modules/bouncer/audience_test.go"
- "modules/bouncer/backend_guard_test.go"
- "modules/bouncer/blacklist.go"
- "modules/bouncer/blacklist_test.go"
- "modules/bouncer/context.go"
- "modules/bouncer/context_test.go"
- "modules/bouncer/cookie_guard_test.go"
- "modules/bouncer/guard.go"
- "modules/bouncer/jwt.go"
- "modules/bouncer/jwt_guard_test.go"
- "modules/bouncer/jwt_test.go"
- "modules/bouncer/mint.go"
- "modules/bouncer/mint_test.go"
- "modules/bouncer/password.go"
- "modules/bouncer/password_test.go"
- "modules/bouncer/phase07_coverage_test.go"
- "modules/bouncer/refresh.go"
- "modules/bouncer/refresh_test.go"
- "modules/bouncer/registry.go"
- "modules/bouncer/registry_coverage_test.go"
- "modules/bouncer/registry_test.go"
- "modules/cabana/README.md"
- "modules/cabana/admin_openapi.go"
- "modules/cabana/admin_paths_test.go"
- "modules/cabana/auth.go"
- "modules/cabana/auth_test.go"
- "modules/cabana/bulk_test.go"
- "modules/cabana/commands.go"
- "modules/cabana/commands_test.go"
- "modules/cabana/contracts.go"
- "modules/cabana/crud.go"
- "modules/cabana/crud_lifecycle_test.go"
- "modules/cabana/crud_test.go"
- "modules/cabana/csrf.go"
- "modules/cabana/export_test.go"
- "modules/cabana/filter_options_test.go"
- "modules/cabana/filter_schema.go"
- "modules/cabana/form_schema.go"
- "modules/cabana/form_schema_test.go"
- "modules/cabana/http.go"
- "modules/cabana/lang.go"
- "modules/cabana/list_schema.go"
- "modules/cabana/list_schema_test.go"
- "modules/cabana/messages.go"
- "modules/cabana/messages_test.go"
- "modules/cabana/metadata_settings_test.go"
- "modules/cabana/navigation.go"
- "modules/cabana/openapi_conformance_test.go"
- "modules/cabana/phase09_contract_test.go"
- "modules/cabana/phase10_auth_test.go"
- "modules/cabana/phase10_coverage_test.go"
- "modules/cabana/phase10_csrf_test.go"
- "modules/cabana/prefix.go"
- "modules/cabana/query.go"
- "modules/cabana/query_test.go"
- "modules/cabana/refresh_revocation_test.go"
- "modules/cabana/registry.go"
- "modules/cabana/relation.go"
- "modules/cabana/relation_field.go"
- "modules/cabana/relation_field_test.go"
- "modules/cabana/relation_test.go"
- "modules/cabana/schema.go"
- "modules/cabana/schema_types.go"
- "modules/cabana/security_coverage_test.go"
- "modules/cabana/security_test.go"
- "modules/cabana/settings.go"
- "modules/cabana/testdata/list/all_columns.yaml"
- "modules/cabana/testdata/list/all_filters.yaml"
- "modules/compass/README.md"
- "modules/compass/config.go"
- "modules/compass/config_test.go"
- "modules/compass/env.go"
- "modules/compass/env_test.go"
- "modules/compass/persist.go"
- "modules/compass/persist_test.go"
- "modules/festival/README.md"
- "modules/festival/bus.go"
- "modules/festival/bus_test.go"
- "modules/fetchguard/README.md"
- "modules/fetchguard/fetch.go"
- "modules/fetchguard/fetch_coverage_test.go"
- "modules/fetchguard/fetch_test.go"
- "modules/fetchguard/ip.go"
- "modules/fetchguard/ip_test.go"
- "modules/fetchguard/policy.go"
- "modules/lagoon/README.md"
- "modules/lagoon/attach/app_test.go"
- "modules/lagoon/attach/bucket.go"
- "modules/lagoon/attach/bucket_test.go"
- "modules/lagoon/attach/file.go"
- "modules/lagoon/attach/file_test.go"
- "modules/lagoon/attach/lifecycle_test.go"
- "modules/lagoon/attach/migrations.go"
- "modules/lagoon/attach/static.go"
- "modules/lagoon/attach/static_test.go"
- "modules/lagoon/attach/thumb.go"
- "modules/lagoon/attach/thumb_test.go"
- "modules/lagoon/backend_admin_migrations.go"
- "modules/lagoon/backend_admin_migrations_test.go"
- "modules/lagoon/commands.go"
- "modules/lagoon/connection.go"
- "modules/lagoon/connection_test.go"
- "modules/lagoon/encrypted.go"
- "modules/lagoon/encrypted_test.go"
- "modules/lagoon/fill.go"
- "modules/lagoon/fill_fuzz_test.go"
- "modules/lagoon/fill_test.go"
- "modules/lagoon/hidden_marshal_test.go"
- "modules/lagoon/jsonable.go"
- "modules/lagoon/jsonable_test.go"
- "modules/lagoon/keygen.go"
- "modules/lagoon/keygen_test.go"
- "modules/lagoon/laravel_decrypt.go"
- "modules/lagoon/laravel_decrypt_test.go"
- "modules/lagoon/lifecycle.go"
- "modules/lagoon/lifecycle_test.go"
- "modules/lagoon/migrations.go"
- "modules/lagoon/migrations_test.go"
- "modules/lagoon/order.go"
- "modules/lagoon/order_test.go"
- "modules/lagoon/paginate.go"
- "modules/lagoon/paginate_test.go"
- "modules/lagoon/postgres_test.go"
- "modules/lagoon/relations.go"
- "modules/lagoon/relations_test.go"
- "modules/lagoon/validate.go"
- "modules/lagoon/validate_test.go"
- "modules/pact/README.md"
- "modules/pact/capabilities.go"
- "modules/pact/capabilities_test.go"
- "modules/party/README.md"
- "modules/party/registry.go"
- "modules/party/registry_test.go"
- "modules/phrasebook/README.md"
- "modules/phrasebook/backend/lang/en/lang.yaml"
- "modules/phrasebook/backend/lang/pl/lang.yaml"
- "modules/phrasebook/lang.go"
- "modules/phrasebook/lang/en/validate.yaml"
- "modules/phrasebook/lang/pl/validate.yaml"
- "modules/phrasebook/loader.go"
- "modules/phrasebook/phase10_test.go"
- "modules/phrasebook/translator.go"
- "modules/phrasebook/translator_test.go"
- "modules/postcard/README.md"
- "modules/postcard/assets/default.htm"
- "modules/postcard/drivers.go"
- "modules/postcard/mailer.go"
- "modules/postcard/mailer_test.go"
- "modules/postcard/mailpit_test.go"
- "modules/postcard/smtp_test.go"
- "modules/postcard/templates.go"
- "modules/postcard/templates_test.go"
- "modules/surf/README.md"
- "modules/surf/admin_prefix_test.go"
- "modules/surf/bodylimit.go"
- "modules/surf/bodylimit_test.go"
- "modules/surf/clientip.go"
- "modules/surf/clientip_test.go"
- "modules/surf/cors.go"
- "modules/surf/cors_coverage_test.go"
- "modules/surf/cors_test.go"
- "modules/surf/limiter.go"
- "modules/surf/limiter_coverage_test.go"
- "modules/surf/limiter_store.go"
- "modules/surf/limiter_test.go"
- "modules/surf/locale_from_principal.go"
- "modules/surf/locale_from_principal_test.go"
- "modules/surf/middleware_test.go"
- "modules/surf/params.go"
- "modules/surf/params_test.go"
- "modules/surf/routelist_command.go"
- "modules/surf/router.go"
- "modules/surf/router_test.go"
- "modules/surf/routetable.go"
- "modules/surf/routetable_coverage_test.go"
- "modules/surf/routetable_test.go"
- "modules/surf/serve.go"
- "modules/surf/serve_test.go"
- "modules/tide/README.md"
- "modules/tide/capture_test.go"
- "modules/tide/diff.go"
- "modules/tide/diff_contract_test.go"
- "modules/tide/diff_test.go"
- "modules/tide/fixture.go"
- "modules/tide/flow.go"
- "modules/tide/flow_contract_test.go"
- "modules/tide/flow_test.go"
- "modules/tide/headers_test.go"
- "modules/tide/manifest.go"
- "modules/tide/manifest_contract_test.go"
- "modules/tide/manifest_test.go"
- "modules/tide/normalize.go"
- "modules/tide/normalize_test.go"
- "modules/tide/proxy.go"
- "modules/tide/proxy_security_test.go"
- "modules/tide/proxy_test.go"
- "modules/tide/record.go"
- "modules/tide/replay.go"
- "modules/tide/report.go"
- "modules/tide/roundtrip_test.go"
- "modules/tide/rules.go"
- "modules/tide/rules_test.go"
- "modules/tide/testdata/one-route-spec.yaml"
- "modules/tide/variables.go"
- "modules/towel/README.md"
- "modules/towel/context.go"
- "modules/towel/context_test.go"
- "modules/wire/README.md"
- "modules/wire/response.go"
- "modules/wire/response_coverage_test.go"
- "modules/wire/response_test.go"
- "modules/wristband/README.md"
- "modules/wristband/authorize.go"
- "modules/wristband/authorize_test.go"
- "modules/wristband/client_issue.go"
- "modules/wristband/consent.go"
- "modules/wristband/consent_test.go"
- "modules/wristband/crypto.go"
- "modules/wristband/phase08_coverage_test.go"
- "modules/wristband/redirect_html.go"
- "modules/wristband/register.go"
- "modules/wristband/registration_test.go"
- "modules/wristband/server.go"
- "modules/wristband/server_test.go"
- "modules/wristband/stores.go"
- "modules/wristband/token.go"
- "modules/wristband/token_test.go"
- "scripts/check-admin-dist.sh"
- "scripts/check-admin-openapi.sh"
- "scripts/check-phase10.2.sh"
- "scripts/check-phase10.sh"
- "scripts/check-phase2.sh"
- "scripts/check-phase3.sh"
- "scripts/check-phase4.sh"
- "scripts/check-phase9.sh"
covered_digest: "v2:sha256:f596349d38060d89072317bddbd0096e49f059c82a2d8dcbea7b7e7aba2f5278"
behavior_unverified: 0
overrides_applied: 0
re_verification:
previous_status: gaps_found
previous_score: 6/7
gaps_closed:
- "D-07: Each modules/<name>/ has a short code-derived README with a valid example entry point."
gaps_remaining: []
regressions: []
---
# Phase 10.2: Nest Framework Packages Under Modules and Write Run Docs — Verification Report
**Phase Goal:** The 18 beach-named framework packages live under `modules/<name>/` with the same names and a single root `go.mod`; importers in summercms.go, examples, and fonoteka.go use `git.golem15.com/golem15/summercms/modules/<name>`; each module has a short README; the root README is honest run/onboarding docs.
**Verified:** 2026-09-28T12:11:41Z
**Status:** passed
**Re-verification:** Yes — after gap closure
## Goal Achievement
### Observable Truths
| # | Truth | Status | Evidence |
| --- | --- | --- | --- |
| 1 | D-01/D-02/D-06: All 18 unchanged beach packages live only at `modules/<name>/`; none remains at repository root. | ✓ VERIFIED | Enumerated all 18: each directory exists under `modules/`, no root directory exists, and each first package clause matches its beach name. |
| 2 | D-03: The root layout remains and there is one framework `go.mod`, with no per-package module or `go.work` entry. | ✓ VERIFIED | `go.work` lists only `.` plus the four `examples/hello*` modules; `find modules -name go.mod` is empty. |
| 3 | D-04/D-05: Framework, examples, and Fonoteka importers use nested paths; app replace directives still target this checkout. | ✓ VERIFIED | A corrected tracked-source scan over both repositories found zero root-form beach imports. All named nested imports compile; Fonoteka root and plugin `go.mod` files retain their local framework replaces. |
| 4 | D-05: Both repositories and example module contexts vet/test on the nested graph. | ✓ VERIFIED | `scripts/check-phase10.2.sh --all` passed outside the sandbox, including framework and Fonoteka root/plugin vet/tests. Explicit example vet plus compile-only test also passed. |
| 5 | D-07: Every module README is short, code-derived onboarding with a valid example entry point. | ✓ VERIFIED | All 18 three-line READMEs cite real code. Party now names `party.Plugin`, `party.Register`, and `party.Activate`, all defined in `modules/party/registry.go`. |
| 6 | D-08: Root README honestly explains framework/app separation, local admin recreation, and guarded Phase 15 cutover. | ✓ VERIFIED | README points to Fonoteka's DSN/migrate/serve flow, `/plytadmin`, PHP deployment docs, and matches the Phase 15 note plus `fonoteka.go/config/backend.yaml`. |
| 7 | The Phase 10.2 gate fails closed for layout/import/README/stale-status regressions. | ✓ VERIFIED | `bash -n scripts/check-phase10.2.sh && scripts/check-phase10.2.sh --self-test` passed; its scratch cases independently plant all four forbidden states, including a tracked historical `.planning/` import that must be ignored. |
**Score:** 7/7 truths verified (0 present, behavior-unverified)
## Required Artifacts
| Artifact | Expected | Status | Details |
| --- | --- | --- | --- |
| `modules/` and `modules/festival/` | 18 nested package directories | ✓ VERIFIED | Directory-level check: 18 expected names, matching package clauses, no root shadows. |
| `scripts/check-admin-openapi.sh` | OpenAPI scans moved cabana | ✓ VERIFIED | Uses `--dir modules/cabana`. |
| `scripts/check-admin-dist.sh` / `admin/vite.config.ts` | Boardwalk dist wiring | ✓ VERIFIED | Both reference `modules/boardwalk/dist`; Vite `outDir` is `../modules/boardwalk/dist`. |
| `internal/build/stubs/plugin.tmpl` | Generated plugin imports use nested paths | ✓ VERIFIED | Imports backpack, bonfire, pact, and party through `/modules/`. |
| `modules/*/README.md` | Accurate short module onboarding | ✓ VERIFIED | All exist, are 3 lines, contain no planning prose, and cite valid package entry points. |
| `README.md` | Framework/application onboarding and honest cutover | ✓ VERIFIED | Source-checked against Fonoteka README/config and Phase 15 cutover note. |
| `scripts/check-phase10.2.sh` | Fail-closed hygiene and Go gate | ✓ VERIFIED | Executable; syntax, detector self-test, and full `--all` run passed. |
## Key Link Verification
| From | To | Via | Status | Details |
| --- | --- | --- | --- | --- |
| `modules/backpack/app.go` | `modules/festival` | Nested festival import | ✓ WIRED | Imports `git.golem15.com/golem15/summercms/modules/festival`. |
| Admin/OpenAPI/dist scripts and Vite | moved cabana/boardwalk paths | Retargeted literals | ✓ WIRED | All prescribed `modules/` paths are present in the live scripts/config. |
| `../fonoteka.go/go.mod` | this framework checkout | local replace | ✓ WIRED | `replace git.golem15.com/golem15/summercms => ../summercms.go` remains intact. |
| Root README | per-module READMEs and Fonoteka README | links/run commands | ✓ WIRED | Root README links all 18 module documents and the Fonoteka database setup. |
| Phase gate | layout/import/README/status checks | `--self-test` plants | ✓ WIRED | Each detector is called through `check_hygiene` and must reject its scratch mutation. |
## Data-Flow Trace (Level 4)
Not applicable. This phase moves static Go packages and adds documentation/hygiene tooling; it does not render dynamic data.
## Behavioral Spot-Checks
| Behavior | Command | Result | Status |
| --- | --- | --- | --- |
| Gate detector behavior | `bash -n scripts/check-phase10.2.sh && scripts/check-phase10.2.sh --self-test` | `phase10.2 self-test passed` | ✓ PASS |
| Both-repository migration graph | `scripts/check-phase10.2.sh --all` | Framework and Fonoteka root/plugin packages passed; `phase10.2 check passed` | ✓ PASS |
| Nested example consumers resolve | `go vet ./examples/hello/... ... && go test -run '^$' ./examples/hello/... ...` | hello, base, greeter, optional all completed successfully | ✓ PASS |
| Party README entry point | `go test ./modules/party -count=1` plus source check | Package test passed; README names existing `Plugin`, `Register`, and `Activate` declarations | ✓ PASS |
The initial sandbox `--all` failure was environmental (read-only shared Go cache and denied localhost listeners); the unchanged full command passed outside that sandbox.
## Probe Execution
Not applicable — the plans declare no phase probe and no conventional probe script is in scope.
## Requirements Coverage
No requirement IDs are assigned: both PLAN frontmatters use `requirements: []` and ROADMAP/REQUIREMENTS.md list Phase 10.2 as TBD. No orphaned Phase 10.2 requirement mapping was found.
## Decision Coverage
No CONTEXT.md exists for this phase, so the non-blocking decision-coverage gate was skipped.
## Test Quality Audit
No requirement-linked standalone test file is declared. The shell gate's behavioral self-test has active, fail-first scratch assertions for each detector; no disabled test patterns or circular expected-output generation were found in the phase gate.
## Prohibitions and Anti-Patterns
| Check | Status | Evidence |
| --- | --- | --- |
| No beach-name remapping | ✓ VERIFIED | Package clauses retain all beach names. |
| No module-local `go.mod` or new `go.work` entries | ✓ VERIFIED | No `modules/**/go.mod`; workspace contains only root and hello modules. |
| No historical planning-literal rewrite | ✓ VERIFIED | Historical root-form imports remain under `.planning/`; the live gate explicitly excludes and self-tests this case. |
| No dependency additions | ✓ VERIFIED | No phase diff to root/Fonoteka Go or npm dependency manifests. |
| No invented package API in module onboarding | ✓ VERIFIED | `modules/party/README.md:3` now names real `Plugin`, `Register`, and `Activate` declarations. |
| Debt markers in phase docs/gate | ✓ VERIFIED | No unreferenced `TBD`, `FIXME`, or `XXX` comment found. |
## Human Verification
N/A — this is an infrastructure/documentation phase with no UI or runtime interaction introduced. The factual onboarding failure above is directly observable and does not need manual UAT to classify.
## Gaps Summary
None. The prior D-07 documentation gap is closed: Party onboarding now directs readers to the actual `Plugin`, `Register`, and `Activate` API. The layout, import graph, validation gate, and root onboarding regressions remain absent.
_Verified: 2026-09-28T12:11:41Z_
_Verifier: the agent (gsd-verifier)_
Reference in New Issue View Git Blame Copy Permalink