summercms/.planning/STATE.md

gsd_state_version, milestone, milestone_name, status, stopped_at, last_updated, last_activity, progress

gsd_state_version	milestone	milestone_name	status	stopped_at	last_updated	last_activity	progress
1.0	v1.0	milestone	planning	Phase 4 context gathered	2026-09-18T00:14:26.029Z	2026-09-17	total_phases completed_phases total_plans completed_plans percent 15 3 13 13 20

Project State

Project Reference

See: .planning/PROJECT.md (updated 2026-09-16)

Core value: An existing WinterCMS-shaped app can be ported plugin by plugin to a single Go binary without its frontend noticing: the PHP version's API contract is the acceptance test. Current focus: Phase 4 — cli scaffolding, i18n and mail

Current Position

Phase: 4 Plan: Not started Status: Ready to plan Last activity: 2026-09-17

Progress: [██████████] 100%

Performance Metrics

Velocity:

• Total plans completed: 18
• Average duration: 21 min
• Total execution time: 104 min

By Phase:

Phase	Plans	Total	Avg/Plan
01	4	-	-
02	5	-	-
03	4	-	-

Recent Trend:

• Last 5 plans: 02-01 7 min, 02-02 12 min, 02-03 61 min, 02-04 9 min, 02-05 15 min
• Trend: -

Updated after each plan completion | Phase 03 P03-01 | 17 min | 2 tasks | 52 files | | Phase 03 P03-02 | 5 min | 2 tasks | 8 files | | Phase 03 P03-03 | 8 min | 2 tasks | 17 files | | Phase 03 P03-04 | 15 min | 2 tasks | 15 files |

Accumulated Context

Roadmap Evolution

• Phase 2 edited: edited fields: depends_on (Phase 1), goal (summer parity:* on bonfire, no longer a parallel workstream)

Decisions

Decisions are logged in PROJECT.md Key Decisions table. Recent decisions affecting current work:

• Roadmap: gormigrate (not goose) is the migration tool, per STACK.md's more recent reasoning — ARCHITECTURE.md/PITFALLS.md text still says goose in places; treat gormigrate as authoritative when phases 3 and 5 are planned.
• Roadmap: two repos from day one — summercms.go (framework, no app knowledge) and fonoteka.go (sibling app repo, go.work workspace of plugins). Every phase states which repo(s) it writes to.
• Roadmap: the parity harness (Phase 2) and the first vertical slice (Phase 3) are sequenced immediately after kernel foundation, ahead of any further kernel broadening, to avoid the documented Scala-era bottom-up-kernel failure mode.
• [Phase 02]: tide is the framework-owned parity library and does not import Fonoteka — Phase 2 CONTEXT.md discretion; summercms.go must stay app-agnostic
• [Phase 02]: goccy/go-yaml v1.19.2 decodes fixtures with DisallowUnknownField; SaveFlow uses a dedicated encoder so nested literal bodies keep indent — goccy BytesMarshaler re-emitted |- scalars without nested indent; decode still uses the verified library
• [Phase 02]: JSON diffs ignore object key order and fail missing keys or token-type changes at $.path; non-JSON compares bytes at offset — D-13: structural JSON compare with UseNumber, exact bytes for non-JSON
• [Phase 02]: Proxy bind and upstream must be loopback HTTP; incoming Host/URL never selects the origin — T-02-01: pin PHP upstream, ignore client destination, cap bodies
• [Phase 02]: Capture rules and a private 0600 --vars store drive {{name}} substitution; unclassified credential shapes fail fixture writes — D-07 D-11 and T-02-02: never commit live JWT, inv_ tokens, OAuth codes or PKCE verifiers
• [Phase 02]: Carbon *_at values must match +00:00 before masking; Z, string ids, null vs [] and missing keys fail at $.path — D-13 D-15: assert shape before mask so parity classes stay visible
• [Phase 02]: 154 is the app manifest validated route count, not a framework constant; --next-batch above 15 is refused — D-16 and the 15-route resume workflow; keep tide generic
• [Phase 02]: Isolated PHP uses a parity-named SQLite file on 127.0.0.1:8423; record/reset refuse any other DB — T-02-05
• [Phase 02]: Client OAuth replay merges /tmp/summercms-parity/pkce.vars after seed; the verifier is not in git — D-07 D-11
• [Phase 02]: newTarget and seedHooks live in the app test package so Phase 3 can swap the synthetic handler for the real app and add a temporary genres SQL hook until POST genres is ported — D-10 D-12: framework tide stays app-agnostic; the handler/seed-hook seam is app-owned
• [Phase 02]: Pending never equals passing: TestParityCorpus reports recorded 154/154 passing 0 pending 154 and does not replay PHP fixtures against the synthetic handler — D-16: unported PHP routes must never count as a Go pass
• [Phase 02]: Unavailable Docker fails TestMain; testing.Short skips the container so the fast loop stays fast — QA-03 and D-12: no false green skip when Postgres cannot start
• [Phase 02]: Fresh PHP self-replay uses disposable MariaDB fonoteka_parity_* plus process-local hex credentials, never the developer DB or caller-supplied PHP_PARITY_TARGET — T-02-01 T-02-05: check-phase2.sh --fresh-php owns the origin and rejects PHP_PARITY_TARGET
• [Phase 02]: Client flows run on a second winter:up after dropping tables so they are not replayed after the mutating 154-route suite — D-16 and 02-03 seed-then-clients: keep route replay and Nuxt/MCP replay on disjoint schemas
• [Phase 02]: Capture-by-reference mismatch is a two-step share:item flow with a live token change on the second /show — D-11 D-13: contract tests exercise RecordFlow/ReplayFlow public APIs, not private helpers
• [Phase 03]: GORM and app services share one pgx-stdlib *sql.DB; the River LISTEN/NOTIFY pool is a Phase 11 seam and is not created in lagoon.Open — DATA-01: one shared pool now; dual-driver River listener deferred
• [Phase 03]: Generated app main stays framework-generic (lagoon.RuntimeCommands + surf.ServeCommand); fonoteka.go/app.Handler is the in-process boot seam for parity tests — summer build cannot import the app package; CLI serve and tests still assemble the same surf router
• [Phase 03]: Empty golem15.user.jwt.secret fails Boot; tests use a fixed test-only HS256 secret and do not issue tokens through a production API — D-11: missing secret must not fall back; token minting stays out of Phase 3
• [Phase 03]: lagoon.OrderBy takes a caller allow-list so the framework never hardcodes Fonoteka table names; the handler passes PHP PolishOrder::ALLOWED_COLUMNS — summercms.go must stay app-agnostic; PolishOrder columns live at the Fonoteka call site
• [Phase 03]: Duplicate non_empty query keys last-win, matching PHP parse_str; invalid then 1 is accepted, 1 then invalid is 422 — PHP parse_str last-wins confirmed with php -r; Go uses vals[len(vals)-1]
• [Phase 03]: Invalid stored context is rewritten to the lowest-ID accessible kind=collection row; auto-provisioning stays out of this slice — Plan 03-02 ports only the JWT default resolve path; CollectionProvisioner is Phase 12
• [Phase 03]: Route constraints compile regex and enum allow-lists at registration; request path text is only matched — D-15 T-03-07: PHP ->where() maps onto surf.Where/WhereIn; malformed and unknown IDs share a 404
• [Phase 03]: A ported route with a trusted seed_hook skips the global PHP bootstrap replay — D-20: unported register/login and POST genres; the hook mints a test-only JWT
• [Phase 03]: Corpus passing increments only after the ported subtest succeeds; pending never counts as passing — QA-04 T-03-06: 154 recorded, 1 passing, 153 pending
• [Phase 03]: Colliding fixture IDs are derived from CanonicalGenres seed order (rock=1, electronic=2, jazz=4) — D-20: set id:token, id:wishlist-album, id:genre from PHP seed order, not user input
• [Phase 03]: Phase 3 gate inlines TestParitySynthetic and CLI record/replay; PHP --fresh-php stays the Phase 2 sign-off because four wishlist album_count routes currently fail on live PHP — check-phase2.sh --fresh-php reports 150/154 on wishlist album_count expected 1 vs live 2. Phase 3 did not change PHP, tide, or those fixtures, so the Phase 3 gate must not fail on that drift.
• [Phase 03]: testcontainers-go v0.44.0 is the STACK-named test dependency for framework lagoon isolation tests, matching the app TestMain — DATA-01 isolation tests need a real ICU pl-PL Postgres. The app already used testcontainers; the framework module now pins the same STACK versions so lagoon tests do not share the app TestMain.
• [Phase 03]: High-severity T-03-01 through T-03-04 and T-03-06 are closed with failing-when-broken tests; token issuing remains test-only until Phase 7 — Roadmap required a security review of the JWT guard. 03-SECURITY-REVIEW.md maps each threat to a passing test; minting tokens through a production API is out of this slice.

Pending Todos

None yet.

Blockers/Concerns

• Phase 8 (OAuth2.1) needs a pre-planning check of wavepath.org/plugins/golem15/oauthserver to resolve whether ClientCredentialsStorage/TokenExchangeStorage are needed — flagged in research/SUMMARY.md Gaps, unresolved.
• Phase 9 (admin schema pipeline / relation manager) is the least-precedented design surface in the research — plan with --research-phase.
• Phase 11 (River dual-driver split) is documented but unverified against a real build — plan with --research-phase and budget a timed-latency test.

Deferred Items

Items acknowledged and carried forward from previous milestone close:

Category	Item	Status	Deferred At
(none — first milestone)

Session Continuity

Last session: 2026-09-18T00:14:26.005Z Stopped at: Phase 4 context gathered Resume file: .planning/phases/04-cli-scaffolding-i18n-and-mail/04-CONTEXT.md