17 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, estimate, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | estimate | must_haves | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 10.2-nest-framework-packages-under-modules-and-write-run-docs | 02 | execute | 2 |
|
|
true |
|
|
Phase Goal
Write run docs for the nested modules and a fail-closed hygiene gate so a newcomer can onboard from the root README and the layout cannot silently regress.
After 10.2-01 is green, write eighteen short module READMEs from the code (D-07), replace the root README (D-08), and ship scripts/check-phase10.2.sh plus both-repo vet/test as the last-plan unit/hygiene gate.Purpose: The current root README still claims nothing runs. That is false after Phase 10. Module READMEs and an honest cutover section are the onboarding surface; the gate is Dimension 8 evidence (no VALIDATION.md this run).
Output: modules/<name>/README.md × 18, rewritten README.md, scripts/check-phase10.2.sh.
Repo: summercms.go only for the doc files; the gate also runs ../fonoteka.go tests. Commit docs separately from any leftover code fix; never add co-author tags.
<execution_context>
@/.claude/gsd-core/workflows/execute-plan.md
@/.claude/gsd-core/templates/summary.md
</execution_context>
Artifacts this phase produces
modules/<name>/README.mdfor backpack, boardwalk, bonfire, bouncer, cabana, compass, festival, fetchguard, lagoon, pact, party, phrasebook, postcard, surf, tide, towel, wire, wristband- Rewritten root
README.md(framework-only, two-repo replace, admin-login recreate, Phase 15 not-yet cutover, links to module READMEs) scripts/check-phase10.2.shwith--self-testand--all- Gate checks (not new Go test names): leftover root beach dir; leftover root-form beach import; missing module README; stale root Status sentence;
go vet/go testboth repos
Each file is one paragraph: what the package is for, who imports it (framework peers and/or ../fonoteka.go plugins), and one example entry point such as festival.Bus, compass.Config, cabana.Activate, boardwalk.Handler, surf.BuildRouter, or the owning .go file. No architecture essays. Do not copy .planning/ notes, ROADMAP, or phase plans into these files. Do not invent APIs that are not in the tree. Do not add a per-package go.mod.
test -f modules/festival/README.md && test -f modules/cabana/README.md && test -f modules/compass/README.md && wc -l modules//README.md | awk 'BEGIN{bad=0} $2!="total" && ($1<2 || $1>40){bad=1; print} END{exit bad}'
<fails_when>non-zero exit; any of the 18 modules//README.md missing; a README is under 2 lines or over 40 lines (essay or stub)</fails_when>
<acceptance_criteria>
- for n in backpack boardwalk bonfire bouncer cabana compass festival fetchguard lagoon pact party phrasebook postcard surf tide towel wire wristband; do test -f modules/$n/README.md || exit 1; done exits 0.
- Each README names at least one exported identifier or file (grep for a . type or a .go filename).
- grep -l 'D-0' modules/*/README.md prints nothing (no planning-decision paste).
</acceptance_criteria>
Eighteen short module READMEs exist, each derived from the code, each naming an entry point.
- What this repo is: SummerCMS Go framework only. The application is the sibling ../fonoteka.go (or fonoteka.go next to this repo). This tree is not the app binary.
- Two-repo layout: development uses a go.work / replace of git.golem15.com/golem15/summercms onto this checkout (cite ../fonoteka.go/go.mod and examples/hello/go.mod). Single go.mod here (D-03). Framework libraries live under modules/.
- Recreate the Phase 10 admin login that already worked: point at fonoteka.go for DSN (SUMMER_DATABASE__DSN), pl-PL Postgres,
summer build,./bin/fonoteka migrate,./bin/fonoteka serve. Admin SPA is embed.FS in that binary; fonoteka backend.uri is /plytadmin. Do not list a summer serve of this repo as the way to open admin. Do not invent extra flags. - Honest cutover: drawn only from .planning/notes/go-vs-php-on-plytarium.md. Working local admin login is not a DNS flip of plytarium.com. Flip is Phase 15 after jobs/search (11) and remaining API routes (12-14). Until then, pointing production at this binary would take the public Nuxt app and MCP offline. Operator procedure stays in the PHP docs/deploy/plytarium.com.md. Do not write a production runbook.
- Modules: point at modules/<name>/README.md instead of listing beach names as root directories. A short link list to the 18 README files is enough.
Keep a short Why Go / v1-target pointer if useful (existing .planning/notes/why-go-not-scala.md and v1-target-plytarium.md). Remove the current Status sentence that claims nothing runs. Do not paste planning docs. Do not add secrets or a sample production DSN.
test -f README.md && grep -q 'fonoteka.go' README.md && grep -q 'modules/' README.md && grep -q 'plytadmin' README.md && grep -q 'Phase 15' README.md && grep -q 'docs/deploy/plytarium.com.md' README.md
<fails_when>non-zero exit; any required grep prints no matching line</fails_when>
<acceptance_criteria>
- README.md contains the strings fonoteka.go, modules/, SUMMER_DATABASE__DSN or a clear pointer to the fonoteka.go Database setup section, plytadmin, Phase 15, and docs/deploy/plytarium.com.md.
- README.md does not contain the current Status sentence from the rewrite-summercms-readme todo (the one that says planning-and-research and that nothing runs).
- README.md does not contain a step-by-step nginx/systemd production deploy procedure.
- README.md links at least one modules/<name>/README.md path.
</acceptance_criteria>
Root README onboards a developer to the two-repo layout, the already-working admin login via fonoteka.go, and an honest Phase 15 cutover, and it points at module READMEs.
--all must fail closed when any of these is true:
- Any of the 18 beach names is a directory at the summercms.go repo root.
- Any tracked
*.go,*.tmpl, or*.shin this repo or ../fonoteka.go still contains a root-form beach import (git.golem15.com/golem15/summercms/+ name, with no/modules/segment). Build the needle from a NAMES array plus the module prefix so the script file is not itself a hit; skip this script and skip.planning/. Do not scan historical PLAN.md files. - Any modules/<name>/ for those 18 names lacks README.md.
- Root README.md still contains the stale Status sentence named in the rewrite-summercms-readme todo.
go vet ./...orgo test ./...fails in summercms.go, orgo vet ./... ./plugins/golem15/fonoteka/... ./plugins/golem15/user/...or the matchinggo testfails in ../fonoteka.go.
--self-test: bash -n; in a scratch copy, plant each of (1)-(4) one at a time and refuse unless the script exits non-zero and the stderr names that rule (leftover root dir, old import, missing README, stale Status). Do not run the full both-repo go test inside --self-test.
Reuse the same go vet / go test commands that already worked in 10.2-01 Task 3. Do not invoke check-phase10.sh SPA, OpenAPI, or dist stages. No new dependencies.
bash -n scripts/check-phase10.2.sh && scripts/check-phase10.2.sh --self-test && scripts/check-phase10.2.sh --all
<fails_when>non-zero exit; --self-test output lacks a passed line or contains "refuse:" for the clean tree; --all prints "refuse:" or a package FAIL</fails_when>
<acceptance_criteria>
- test -x scripts/check-phase10.2.sh succeeds.
- --self-test exits 0 on the committed tree and has planted-failure coverage for leftover root dir, old import, missing module README, and stale root Status.
- --all exits 0 on the committed tree.
- A one-off mkdir backpack at repo root followed by the layout stage (or --all) exits non-zero; remove the dir after.
</acceptance_criteria>
The 10.2 gate fails closed on layout, import, README, and stale-status regressions, and both repos stay vet/test green.
<threat_model>
Trust Boundaries
| Boundary | Description |
|---|---|
| Operator → root README | Onboarding text can send someone at production or leak a procedure that is not ours yet |
| Hygiene script → working tree | A gate that greps missing old paths, or that matches its own needle, goes green or red for the wrong reason |
| Module README → public git | Pasted planning notes would publish deferred/internal decisions |
STRIDE Threat Register
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|---|---|---|---|---|---|
| T-10.2-06 | Information Disclosure | README.md cutover / login sections | high | mitigate | Point at fonoteka.go for DSN/migrate/serve; no production runbook; cite PHP docs/deploy/plytarium.com.md; no sample secrets (D-08) |
| T-10.2-07 | Tampering | scripts/check-phase10.2.sh | high | mitigate | Fail closed on leftover root beach dirs, root-form imports, missing module READMEs, and the stale Status sentence; --self-test plants each rule |
| T-10.2-08 | Information Disclosure | modules/*/README.md | low | accept | Explore-quality one-paragraph files; D-07 forbids planning-doc paste; residual risk is a bland public description of exported types |
| T-10.2-09 | Repudiation | --self-test skipped | medium | mitigate | --all is not a substitute for --self-test; Task 3 verify runs both; a self-test that accepts a plant must refuse |
| T-10.2-SC | Tampering | npm/pip/cargo installs | high | mitigate | Docs and a bash gate only; no package-manager installs |
| </threat_model> |
<success_criteria>
- Eighteen module READMEs and a rewritten root README satisfy D-07 and D-08.
- scripts/check-phase10.2.sh fails closed on the four hygiene/docs signals and keeps both repos green. </success_criteria>