docs(31): split into 31, 31.1 and 31.2 and record the planning decisions

This commit is contained in:
Jakub Zych
2026-11-13 11:29:37 +01:00
parent 7b25fcff55
commit 2acf8e46c4
5 changed files with 71 additions and 11 deletions

View File

@@ -46,7 +46,9 @@ Decimal phases appear between their surrounding integers in numeric order.
- [ ] **Phase 19.8: Console commands overhaul** - `diary` logging module, Artisan-grade global flags, help and `list` in `bonfire`, sweep of every command
- [ ] **Phase 20: Demo instance with every shared plugin** - Add the chat family (chat, channels, video calls, chatbots, forum, herald, friends) to the live demo from Phase 19.4.1
- [ ] **Phase 30: Płytarium cutover** - Parity harness green, both real clients run unchanged in production
- [ ] **Phase 31: Chat polish against WavePath clients** - Replay WavePath's chat traffic through `tide` against the ported chat plugins until green
- [ ] **Phase 31: Chat polish against WavePath clients** - `tide` additions, `sm-wavepath-app`, the full PHP recording of WavePath's community routes and the foundation slice green
- [ ] **Phase 31.1: WavePath messaging parity** (INSERTED) - Group chat, channels, DMs, threads, commands and attachments replay green
- [ ] **Phase 31.2: WavePath satellites parity and close-out** (INSERTED) - Presence, push, webhooks, bot, video, guests, forums and notes; zero pending
## Phase Details
@@ -1579,23 +1581,63 @@ Plans:
### Phase 31: Chat polish against WavePath clients
**Goal:** The ported chat and chat satellites carry WavePath's chat traffic exactly as PHP does. The chat routes that WavePath's clients call are recorded with `tide`, replayed against the Go plugins and fixed until green, so that chat, the core feature of WavePath, is not the risk in the WavePath migration.
**Goal:** WavePath's community traffic is recorded from the PHP backend with `tide` and replayed against a Go app, so that chat, the core feature of WavePath, is not the risk in the WavePath migration. This phase delivers the harness and the corpus: the `tide` additions, the `sm-wavepath-app` skeleton, the local PHP stack and scenario, the full PHP recording, and the foundation slice (groups, members, invites, friends, realtime authorization) ported and green. Phases 31.1 and 31.2 port the rest of the corpus (split at planning, 2026-11-13).
**Mode:** mvp
**Depends on:** Phase 19, Phase 19.1, Phase 30 (formerly Phase 19.2; moved 2026-10-18 so the `tide` recording is made just before the WavePath migration, while the PHP routes still move)
**Repos:** `sm-chat-plugin`, `sm-chatchannels-plugin` and the satellite repos; `summercms.go` only for `lighthouse` or `tide` gaps
**Depends on:** Phase 19, Phase 19.1 (formerly Phase 19.2; the Phase 30 dependency was sequencing only and is dropped, 31 D-05)
**Repos:** `sm-wavepath-app` (new); `sm-chat-plugin`, `sm-chatchannels-plugin`, `sm-chatbots-plugin`, `sm-chatvideo-plugin`, `sm-forum-plugin`, `sm-herald-plugin`, `sm-userfriends-plugin`; `sm-user-plugin` (additive only); `summercms.go` only for `tide` or `lighthouse` gaps; `sm-demo-app`, `sm-bm-app` and the vue layers to follow shared-plugin changes; `sm-oauthserver-plugin` for the OIDC parity recording
**Requirements**: TBD
**Success Criteria** (what must be TRUE):
1. A `tide` corpus of the chat, channel, thread, video-room and push routes, recorded from the PHP backend through `vue-wavepath-app`, `wavepath-mcp` and `hubot-wavepath`, replays green against the Go plugins.
2. Realtime events on the `chat`, `video` and `presence:` namespaces match the PHP broadcasts recorded by the `tide` Centrifugo recorder.
3. Behaviour stays neutral to the other consumers of these plugins (QuestStream, Horoskopia, Portal). Framework READMEs and docs still name no application.
4. The new code has unit tests, delivered in the phase's last plan.
1. A `tide` corpus of the whole community surface (31 D-09: every route under `/_wave/api/v1/community`, the guest, push, bot and token routes and the webhook, 196 routes) is recorded from the PHP backend through `vue-wavepath-app` and `hubot-wavepath`, with hand-written cases for the routes no client calls, and replays green against PHP itself.
2. Every writing case of the corpus has a broadcast golden with all publications PHP sent for it, on any namespace (31 D-10), and outbound vendor calls are recorded as upstream sidecars.
3. The foundation slice (groups, members, invites, join, friends, realtime authorization) is `ported` in `sm-wavepath-app` and replays green, broadcasts included. A gate script reports the pending count of the remaining routes and fails closed.
4. Behaviour stays neutral to the other consumers of these plugins: `sm-bm-app` and `sm-demo-app` build and pass their tests with the released plugin versions (31 D-14). Framework READMEs and docs still name no application.
5. The new code has unit tests, delivered in the phase's last plan.
**Plans:** 0 plans
Plans:
- [ ] TBD (run /msd-plan-phase 31 to break down)
### Phase 31.1: WavePath messaging parity (INSERTED)
**Goal:** The messaging routes of the WavePath corpus recorded in Phase 31 replay green against Go: group chat, channels, direct messages, threads, commands, reactions, emoji, preferences, pins and attachments, including the attachment streaming delta with Range support (31 D-12) released in `sm-chat-plugin`.
**Mode:** mvp
**Depends on:** Phase 31
**Repos:** `sm-wavepath-app`; the shared chat plugin repos for parity fixes; `sm-demo-app`, `sm-bm-app` and the vue layers to follow
**Requirements**: TBD
**Success Criteria** (what must be TRUE):
1. Every group chat, channel, DM, thread, command, reaction, emoji, preference, pin and attachment route of the corpus is `ported` with passing cases, and its broadcast goldens are asserted.
2. Attachment downloads answer Range requests as PHP does (206, 416, `Accept-Ranges`), released as a `sm-chat-plugin` patch tag with a changelog post.
3. `sm-bm-app` and `sm-demo-app` build and pass their tests with the released plugin versions before each plugin tag (31 D-14).
4. The new code has unit tests, delivered in the phase's last plan.
**Plans:** 0 plans
Plans:
- [ ] TBD (run /msd-plan-phase 31.1 to break down)
### Phase 31.2: WavePath satellites parity and close-out (INSERTED)
**Goal:** The rest of the WavePath corpus replays green against Go and the corpus closes at zero pending (31 D-15): presence and status, notifications and push, link unfurl, webhooks, bot REST with the token guard, search, video and guests, forums and shared notes (on a minimal, provisional diary read model).
**Mode:** mvp
**Depends on:** Phase 31.1
**Repos:** `sm-wavepath-app`; the shared plugin repos for parity fixes; `sm-demo-app`, `sm-bm-app` and the vue layers to follow
**Requirements**: TBD
**Success Criteria** (what must be TRUE):
1. Every corpus route is `ported` with passing cases and every broadcast golden and upstream sidecar is asserted. The only non-matching cases are signed entries in the accepted-differences file (31 D-13).
2. The fail-closed gate script in `sm-wavepath-app` passes at zero pending and checks that `sm-bm-app` and `sm-demo-app` build and pass (31 D-15).
3. The security review of the app plugin (guest access, bot and token authentication, webhook, access resolvers) is done and its findings are resolved.
4. The re-record with a drift report can be run unattended (31 D-06).
5. The new code has unit tests, delivered in the phase's last plan.
**Plans:** 0 plans
Plans:
- [ ] TBD (run /msd-plan-phase 31.2 to break down)
### Phase 32: SEO foundation
**Goal:** As a site editor on any SummerCMS application, I want per-record and global SEO in the admin, with redirects and robots.txt, all manageable through MCP, so that every site ships correct, editable SEO without per-site work. The framework gains only generic seams; the SEO code lives in a new shared plugin. This covers:

View File

@@ -5,12 +5,12 @@ current_phase: 35
current_phase_name: Mail templates and layouts editor
status: executing
stopped_at: Completed 35-01-PLAN.md
last_updated: "2026-11-13T10:11:36.542Z"
last_updated: "2026-11-13T10:28:52.958Z"
last_activity: 2026-11-13
last_activity_desc: Phase 35 execution started
state_head: db86b51a51529abb74cbbf8a2a55be1b1a47e073
state_head: 7b25fcff5542abd72df18742aaab435ba8c8b132
progress:
total_phases: 50
total_phases: 52
completed_phases: 37
total_plans: 288
completed_plans: 285
@@ -356,6 +356,8 @@ Progress: [████████░░] 82%
- Phase 32.1 inserted after Phase 32: MCP OAuth for plugin apps: declared scopes, MCP subject on context, per-client MCP consent (requested by a consuming app's agent-access work) (URGENT)
- Phase 34 added: Plugin marketplace: summercms.io/marketplace, summer plugin:install (registry ID or git URL), read-only admin Plugins screen
- Phase 35 added: Mail templates and layouts editor: DB overrides of plugin-registered mail, editable seeded layouts, images; integer phase so follow-ups land as 35.x
- Phase 31.1 inserted after Phase 31: Phase 31 split at planning (2026-11-13): messaging routes of the WavePath community corpus
- Phase 31.2 inserted after Phase 31: Phase 31 split at planning (2026-11-13): satellites, zero-pending gate (31 D-15) and security review
### Decisions

View File

@@ -71,6 +71,20 @@ Out of scope:
- **D-14:** **The PHP shape wins in the shared plugins; consumers follow.** A parity fix corrects the shared serializer or behaviour itself, so the generic `/_x/api/v1` APIs and the `/_wave` aliases keep one serializer set. Each changed plugin gets a patch tag and a changelog post on `/changelog/plugins`, and `sm-demo-app` and the vue layers are updated in this phase. A renamed or removed field is called out in the release notes. The user's condition: "1 is fine as long as sm-bm-app keeps working". Before any plugin tag, `sm-bm-app` (mounts chat, chatchannels and chatbots, with its own frontend) must build with the new plugin commits, pass its tests (`chat_test.go`, `realtime_test.go`), and have its frontend checked against any renamed or removed field. — **Reversibility:** costly — a changed field in a published plugin API reaches every mounting app and vue layer.
- **D-15:** **The phase closes at zero pending.** Every corpus route is `ported` with passing cases, every broadcast golden is asserted, and the only non-matching cases are signed entries in the accepted-differences file. A fail-closed gate script checks this, and checks that `sm-bm-app` and `sm-demo-app` build and pass. The gate lives in `sm-wavepath-app`, because a script in `summercms.go` would name an application.
### Phase split and research answers (decided at planning, 2026-11-13)
- **D-16:** **The work is split into three phases.** Research sized it at 12 to 15 large plans. Phase 31 is the corpus and harness: the `tide` additions (T-1 to T-10 in `31-RESEARCH.md`), the `sm-wavepath-app` skeleton, the PHP stack and the scenario, the full PHP recording of all 196 routes with broadcast and upstream sidecars, PHP self-replay green, the foundation slice ported (envelope, cookie actor, rate buckets, contexts, resolvers, the `wave` and presence authorizers, the realtime routes, groups, members, invites, join, friends, group lifecycle), the three folded todos and a unit-test plan. Phase 31.1 ports messaging and releases the chat Range delta. Phase 31.2 ports the satellites and closes out. This amends three earlier decisions for Phase 31:
- D-15: the zero-pending gate closes Phase 31.2. In Phase 31 the gate script exists, fails closed on any failing or unrecorded case, and reports the pending count; it requires zero pending only for the foundation slice.
- D-12: the manifest is frozen at the recording commit in Phase 31. The chat attachment Range delta is ported in Phase 31.1 and the guest thread and guest identity delta in Phase 31.2.
- D-13: the accepted-differences file is created in Phase 31 and gets entries as routes are ported; the final sign-off is in Phase 31.2. The security review named under Claude's Discretion runs in Phase 31.2, when the guest, bot, token and webhook code exists.
- **D-17:** **Two recording clients, not three.** `wavepath-mcp` calls no corpus route (it calls only diary, practices, trainings, stats, me and state). The corpus is recorded through `vue-wavepath-app` and `hubot-wavepath`. `wavepath-mcp` is recorded with the rest of the WavePath backend in a later phase. D-09's boundary is unchanged.
- **D-18:** **Shared notes stay in the corpus, on a minimal diary read model.** The app plugin gets a small `DiaryEntry` read model and fixture rows, marked provisional for WavePath's agent to replace when the diary is ported. The notes routes are recorded in Phase 31 and ported in Phase 31.2.
- **D-19:** **All 17 routes that no client calls stay in the corpus.** Each gets one hand-written success case recorded from PHP, plus its denial and validation cases.
- **D-20:** **The PHP stack is isolated from the other agent's work.** [informational] The database is an isolated MariaDB container, not the dev database. The pinned submodule commits (`chat` at `fbfbcf9`, `journal`) are read through a git worktree or export under the parity root, so the `wavepath.org` working tree is not changed at all. This is stricter than D-08 allows.
- **D-21:** **Replay logs in without the auth routes.** [informational] Both seeders mint the session JWTs into the `tide` vars store and requests carry them as the `token` cookie; `/_wave/api/v1/auth/login` stays outside the corpus.
- **D-22:** **The slash fix matches WavePath.** WavePath refuses unknown slash text (the SPA blocks it from the command catalog and keeps the draft; PHP answers 422 `unknown_command`). The layer fix is therefore: check the first token against the command catalog client-side, keep the draft on an unknown command, and support a `//` escape that posts the rest as text. Unknown slash text is not posted as text.
Left for the later phases' own discussion: the search backend for the search cases (Typesense or the null driver) and the attachment `url` rewrite (research recommends app-side).
### Claude's Discretion
- Go package, type and route-handler names in the app plugin, and the layout inside `parity/`.
- The scenario's exact rows, as long as every access rule in D-11 has a user on each side of it.

View File

@@ -0,0 +1 @@