28 KiB
28 KiB
phase, verified, status, score, covered_files, covered_digest, behavior_unverified, overrides_applied, re_verification, advisory, human_verification
| phase | verified | status | score | covered_files | covered_digest | behavior_unverified | overrides_applied | re_verification | advisory | human_verification | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 10.2-nest-framework-packages-under-modules-and-write-run-docs | 2026-10-01T21:26:36Z | human_needed | 5/7 must-haves verified |
|
v2:sha256:c5236001a0415018a2c9071eda2ee55201881dadb06f9a3b9437c5bec10a5d91 | 0 | 0 |
|
|
|
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-10-01T21:26:36Z Status: human_needed Re-verification: Yes. The previous report (passed, 7/7) went stale because covered files moved or changed after it was written.
Stale covered files: where they went
| Old path | Fate | Current path |
|---|---|---|
modules/boardwalk/dist/assets/index-BAlwlQ8W.js |
Deleted in 107d820 (10.1-02 admin rebuild), then renamed by later content-hashed rebuilds (a5e7dac, 6b0ac15, 849a9ff, 5bbb0ad) |
modules/boardwalk/dist/assets/index-J-FCndLr.js |
modules/boardwalk/dist/assets/index-CLf0gZ3D.css |
Deleted in 107d820, replaced in 9df9fae |
modules/boardwalk/dist/assets/index-CfeX_snf.css |
Both successors are the bundles modules/boardwalk/dist/index.html references at HEAD. The other 301 entries still exist at the same paths. A cross-check against git log --grep='(10.2' --name-only found no Phase 10.2 implementation file missing from the list. The only commit path not in the list is the pre-move backpack/app.go, which now lives at modules/backpack/app.go and is listed.
Goal Achievement
Observable Truths
| # | Truth | Status | Evidence |
|---|---|---|---|
| 1 | D-01/D-02/D-06: the 18 beach packages live only under modules/<name>/ with unchanged package names, and none is a directory at repo root. |
✓ VERIFIED | All 18 directories exist under modules/. Each package clause matches its beach name. No root shadow exists, and check-phase10.2.sh --layout exits 0. The four modules added later (beachcomber, conga, flare, lighthouse) follow the same layout. |
| 2 | D-03: admin/, cmd/, examples/, internal/, scripts/, go.mod and README.md stay at root; there is one framework go.mod, and go.work uses only . and ./examples/hello*. |
✓ VERIFIED | Root listing confirmed. find modules -name go.mod is empty. go.work lists . plus the four examples/hello* modules. |
| 3 | D-04/D-05: every importer in summercms.go, examples and fonoteka.go uses .../summercms/modules/<name>, and the replace directives still target this checkout. |
✓ VERIFIED | git grep for root-form beach imports outside .planning/ found no matches. check-phase10.2.sh --imports (both repos) exits 0. ../fonoteka.go/go.mod and both plugin go.mod files keep replace git.golem15.com/golem15/summercms => .../summercms.go. |
| 4 | D-05: go vet ./... and go test ./... are green in summercms.go, and the same pair plus the plugin modules is green in fonoteka.go. |
✓ VERIFIED | Framework: go vet ./... exits 0. In the single full go test ./... run, 33 packages passed and 2 failed with timing flakes outside Phase 10.2 (conga, lighthouse). Both passed when rerun alone (see Advisory). fonoteka.go: vet and test over ./... ./plugins/golem15/fonoteka/... ./plugins/golem15/user/... exit 0. Example modules: vet and compile-only test exit 0. |
| 5 | D-07: each modules/<name>/README.md is a short one-paragraph README stating what the package is, who imports it and one example entry point, with no architecture essays or planning prose. |
? UNCERTAIN (superseded) | All 18 READMEs exist, contain no planning prose and no consuming-application names, and the docs checker confirms every identifier they cite exists. They are no longer short, though: 62-211 lines each, rewritten by 3142aeb to the standard structure the CLAUDE.md Documentation rule (fafb12f) requires. The literal must-have is false, and the change looks intentional and user-authored. A human decision is required (see the suggested override). |
| 6 | D-08: the root README states framework-only (app is sibling fonoteka.go), explains the two-repo go.work replace, points at fonoteka.go to recreate the admin login, includes an honest Phase 15 cutover, and links the module READMEs. | ? UNCERTAIN (superseded) | Still true: the framework-only description, the module-path-plus-local-replace pattern, links to all module READMEs, a runnable examples/hello quick start with migrate/serve, and no stale "nothing runs" claim. No longer true: it does not name fonoteka.go, /plytadmin or the Phase 15 cutover. Commit 70d3c39 removed them deliberately to follow the CLAUDE.md rule that framework READMEs never name a consuming application. A human decision is required. |
| 7 | The fail-closed 10.2 gate refuses leftover root beach directories, root-form beach imports, a missing module README and a stale "nothing runs" README. | ✓ VERIFIED | bash -n scripts/check-phase10.2.sh && scripts/check-phase10.2.sh --self-test printed phase10.2 self-test passed. Live --layout, --imports, --readmes and --status each exit 0. |
Score: 5/7 truths verified, 0 present but behavior-unverified, 2 uncertain (superseded by later user decisions; human decision requested)
Suggested overrides (not applied; developer acceptance required)
This looks intentional. To accept the deviations, add to this file's frontmatter:
overrides:
- must_have: "D-07: Each modules/<name>/ has a short README.md of one paragraph stating what the package is, who imports it, and one example entry point (Package.Type or file). No architecture essays and no pasted planning-doc prose."
reason: "Superseded by the CLAUDE.md Documentation rule (fafb12f) and commit 3142aeb: module READMEs follow the standard structure (H1, summary, import line, Overview, Features, Usage, API reference, Dependencies, Testing) and the docs checker verifies every identifier they name."
accepted_by: "{name}"
accepted_at: "{ISO timestamp}"
- must_have: "D-08: Root README.md states this repo is framework only (app is sibling fonoteka.go), explains the two-repo go.work replace during development, tells an operator how to recreate the Phase 10 admin login by pointing at fonoteka.go for DSN/migrate/serve, includes an honest not-yet cutover drawn from .planning/notes/go-vs-php-on-plytarium.md (Phase 15 PHP flip), and links modules/<name>/README.md instead of listing beach names at root."
reason: "Superseded by commit 70d3c39 (generic root README) and the CLAUDE.md rule that framework READMEs never name a consuming application; app-specific run and cutover docs belong to the application repo."
accepted_by: "{name}"
accepted_at: "{ISO timestamp}"
Required Artifacts
| Artifact | Expected | Status | Details |
|---|---|---|---|
modules/ and modules/festival/ |
18 nested package directories | ✓ VERIFIED | 18 expected names present, package clauses match, no root shadows. |
scripts/check-admin-openapi.sh |
OpenAPI scans the moved cabana | ✓ VERIFIED | --dir modules/cabana (line 32). |
scripts/check-admin-dist.sh / admin/vite.config.ts |
Boardwalk dist wiring | ✓ VERIFIED | The script diffs against modules/boardwalk/dist; Vite has outDir: '../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 |
Module onboarding | ⚠️ PRESENT, NOT SHORT | All exist and are accurate (the docs checker passes), but they no longer match D-07's "short" wording (truth 5). |
README.md |
Framework onboarding, two-repo layout, admin-login recreate, honest cutover | ⚠️ PARTIAL BY DESIGN | Generic framework onboarding. The app-specific parts were removed by a later rule (truth 6). |
scripts/check-phase10.2.sh |
Fail-closed hygiene and Go gate | ✓ VERIFIED | Syntax check, self-test and all four hygiene modes pass. |
Key Link Verification
| From | To | Via | Status | Details |
|---|---|---|---|---|
modules/backpack/app.go |
modules/festival |
nested import | ✓ WIRED | Line 8 imports git.golem15.com/golem15/summercms/modules/festival. |
| Admin/OpenAPI/dist scripts and Vite | moved cabana/boardwalk paths | retargeted literals | ✓ WIRED | All modules/ paths present. |
../fonoteka.go/go.mod (+ plugin go.mods) |
this framework checkout | local replace | ✓ WIRED | => ../summercms.go / => ../../../../summercms.go. |
| Root README | per-module READMEs | links | ✓ WIRED | The modules table links all 22 module READMEs (18 from 10.2 plus 4 added later). |
| Phase gate | layout/import/README/status checks | --self-test plants |
✓ WIRED | Self-test passed. |
Data-Flow Trace (Level 4)
Not applicable. The phase moves static Go packages and adds docs and hygiene tooling; it renders no dynamic data.
Behavioral Spot-Checks
| Behavior | Command | Result | Status |
|---|---|---|---|
| Framework vet | go vet ./... |
exit 0 | ✓ PASS |
| Framework tests (single full run) | go test ./... |
33 ok, 2 FAIL (conga TestQueueWork, lighthouse TestBulkEmitsOnce: load timing) | see next row |
| Rerun of the two failing packages | go test -count=1 ./modules/conga ./modules/lighthouse |
both ok | ✓ PASS |
| Docs tree check | go test ./cmd/summer -run TestDocsTree -count=1 |
ok | ✓ PASS |
| Docs build check | go run ./cmd/summer docs:build --check |
docs:build: no problems found |
✓ PASS |
| App repo vet/test | cd ../fonoteka.go && go vet/test ./... ./plugins/golem15/fonoteka/... ./plugins/golem15/user/... |
exit 0 / exit 0 | ✓ PASS |
| Examples | go vet + go test -run '^$' over the four examples/hello* modules |
exit 0 | ✓ PASS |
| Gate self-test | bash -n scripts/check-phase10.2.sh && scripts/check-phase10.2.sh --self-test |
phase10.2 self-test passed |
✓ PASS |
| Gate hygiene | scripts/check-phase10.2.sh --layout / --imports / --readmes / --status |
all exit 0 | ✓ PASS |
No command changed the working tree (git status showed only the pre-existing untracked zip).
Probe Execution
Not applicable. The plans declare no probe, and no conventional scripts/*/tests/probe-*.sh is in scope.
Requirements Coverage
No requirement IDs are assigned: both PLAN frontmatters have requirements: [], and ROADMAP lists Phase 10.2 Requirements as TBD. No orphaned mappings.
Advisory (New Scope, Unevidenced)
| # | Finding | Category | Why Advisory |
|---|---|---|---|
| 1 | conga/lighthouse tests flake under concurrent Docker load | other | Outside Phase 10.2. The packages pass in isolation and their files are not covered by this phase. |
Anti-Patterns Found
| File | Line | Pattern | Severity | Impact |
|---|---|---|---|---|
| (none) | No TBD/FIXME/XXX in the gate, READMEs, stubs, Vite config or admin scripts |
Human Verification Required
1. Accept or reject the D-07 supersession
Test: Compare D-07 ("short one-paragraph module README") with the CLAUDE.md Documentation rule and the current modules/*/README.md files.
Expected: Accept by adding the D-07 override above, or reject and plan a gap closure. A gap closure would conflict with CLAUDE.md.
Why human: Only the developer can accept that a later project rule replaces a phase must-have.
2. Accept or reject the D-08 supersession
Test: Compare D-08 (fonoteka.go, admin-login recreate, Phase 15 cutover in the root README) with commit 70d3c39 and the rule that framework READMEs never name a consuming application.
Expected: Accept by adding the D-08 override above (app-specific run and cutover docs then live in the application repo), or reject.
Why human: Restoring D-08 literally would break a standing CLAUDE.md rule, so the developer has to pick which one wins.
Gaps Summary
There are no implementation gaps. The structural goal holds at HEAD: the nested modules/ layout, a single go.mod, nested imports in both repositories, green vet and tests (aside from two load flakes outside the phase), and a working fail-closed gate. The two documentation must-haves (D-07 short module READMEs, D-08 app-specific root README) no longer hold as written. Later, deliberate, user-authored commits and the CLAUDE.md Documentation rule replaced them. They are routed to the developer as override decisions rather than gaps, because closing them literally would break current project rules.
Verified: 2026-10-01T21:26:36Z Verifier: Claude (gsd-verifier)