Files
summercms/.planning/phases/20-demo-instance-with-every-shared-plugin/20-01-PLAN.md
2026-10-28 18:39:49 +01:00

48 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
20-demo-instance-with-every-shared-plugin 01 execute 1
../sm-chat-plugin/events/events.go
../sm-chat-plugin/contracts/rejection.go
../sm-chat-plugin/classes/service.go
../sm-chat-plugin/classes/writes.go
../sm-chat-plugin/api/errors.go
../sm-chat-plugin/saving_smoke_test.go
../sm-chat-plugin/README.md
../sm-forum-plugin/events/events.go
../sm-forum-plugin/contracts/rejection.go
../sm-forum-plugin/classes/forum_service.go
../sm-forum-plugin/classes/lifecycle.go
../sm-forum-plugin/api/errors.go
../sm-forum-plugin/saving_smoke_test.go
../sm-forum-plugin/README.md
../sm-chatvideo-plugin/go.mod
../sm-chatvideo-plugin/go.sum
../sm-chatvideo-plugin/README.md
../sm-herald-plugin/go.mod
../sm-herald-plugin/go.sum
../sm-herald-plugin/README.md
../sm-userfriends-plugin/go.mod
../sm-userfriends-plugin/go.sum
../sm-userfriends-plugin/README.md
../sm-moderation-plugin/.gitignore
../sm-moderation-plugin/go.mod
../sm-moderation-plugin/go.sum
../sm-moderation-plugin/go.work
../sm-moderation-plugin/plugin.go
../sm-moderation-plugin/admin.go
../sm-moderation-plugin/admin_permissions.go
../sm-moderation-plugin/logger.go
../sm-moderation-plugin/classes/filter.go
../sm-moderation-plugin/classes/filter_smoke_test.go
../sm-moderation-plugin/models/settings.go
../sm-moderation-plugin/models/registry.go
../sm-moderation-plugin/models/settings/fields.yaml
../sm-moderation-plugin/updates/202610280001_create_golem15_moderation_settings.go
../sm-moderation-plugin/updates/registry.go
../sm-moderation-plugin/lang/en/lang.yaml
../sm-moderation-plugin/lang/pl/lang.yaml
../sm-moderation-plugin/config/config.yaml
../sm-moderation-plugin/README.md
false
SC-1
D-17
D-18
D-19
D-20
tokens raw_tokens tasks confidence
220000 220000 6 low
truths artifacts key_links prohibitions
D-18 (chat): with a festival listener on events.MessageSaving that returns contracts.Rejection{Field: "content", Message: m}, POST /_chat/api/v1/conversations/{id}/messages, POST /_chat/api/v1/messages/{id}/replies and PUT /_chat/api/v1/messages/{id} answer 422 {"error":"Validation failed","errors":{"content":[m]}}; no golem15_chat_messages row is inserted or changed, MessageCreated and MessageUpdated do not fire and nothing is published.
D-18 (forum): ForumService.CreateThread, Reply and EditPost fire events.PostSaving before breakwater.Render; a contracts.Rejection from a listener maps to the existing 422 envelope under errors.title or errors.body and nothing is persisted.
D-18 (parity): with no MessageSaving or PostSaving listener every existing route, payload, status, table, migration ID and config key of sm-chat-plugin and sm-forum-plugin is unchanged; their php_method_map_test.go and golden_test.go pass without edits; the seams name no application and ship as patch-level additions.
D-17: the new shared plugin golem15.moderation (module git.golem15.com/golem15/sm-moderation-plugin) publishes *classes.Filter at boot; Filter.Check returns a Violation for a banned word or phrase (case-insensitive, Unicode letter boundaries, Polish letters included) or a banned link (a listed domain, its subdomains, with or without scheme or www, and URL-prefix entries), and nil for clean text; the lists are the banned_words and banned_links textareas of its admin settings screen (singleton golem15_moderation_settings) behind the permission golem15.moderation.manage_settings; the plugin imports neither chat nor forum.
SC-1: sm-chatvideo-plugin, sm-herald-plugin and sm-userfriends-plugin go.mod files keep only the framework replace and require sm-chat-plugin v0.1.3, sm-user-plugin v0.1.13 and summercms v0.5.1 where they depend on them; every one of the eight repos passes go vet and go test -short, and the five chat dependants build with GOWORK=off.
SC-1 (release, after the Task 5 go-ahead): origin of each repo carries its new tag on the pushed HEAD that passed the checks: sm-chat-plugin v0.1.4 (patch, the seam), sm-chatchannels-plugin, sm-chatbots-plugin, sm-chatvideo-plugin, sm-forum-plugin, sm-herald-plugin, sm-userfriends-plugin and sm-moderation-plugin v0.1.0 (or the next free number read from the remote); a scratch module requiring all eight tags and summercms v0.5.1 builds with GOWORK=off.
D-20 (D-19 superseded): this is plan 01 of the six plans confirmed at plan time; the chat family release precedes the demo backend (plan 02).
path provides contains
../sm-chat-plugin/events/events.go MessageSaving pre-save event and MessageSavingEventName MessageSaving
path provides contains
../sm-chat-plugin/contracts/rejection.go Rejection{Field, Message} error a pre-save listener returns type Rejection struct
path provides contains
../sm-forum-plugin/events/events.go PostSaving pre-save event and PostSavingEventName PostSaving
path provides contains
../sm-forum-plugin/contracts/rejection.go Rejection{Field, Message} for forum listeners type Rejection struct
path provides contains
../sm-moderation-plugin/classes/filter.go Filter, NewFilter, Check, Match, ParseList, Violation func (f *Filter) Check
path provides contains
../sm-moderation-plugin/admin.go moderation_settings settings item (HasSettings, HasLang) moderation_settings
from to via pattern
../sm-chat-plugin/classes/service.go ../sm-chat-plugin/events/events.go SendMessageWith fires MessageSaving on s.bus before lagoon.Transaction MessageSaving{
from to via pattern
../sm-chat-plugin/api/errors.go ../sm-chat-plugin/contracts/rejection.go writeChatError maps errors.As(err, &contracts.Rejection) to writeValidation errors.As(err, &rej)
from to via pattern
../sm-forum-plugin/classes/forum_service.go ../sm-forum-plugin/events/events.go CreateThread and Reply fire PostSaving on s.bus before breakwater.Render PostSaving{
from to via pattern
../sm-moderation-plugin/plugin.go ../sm-moderation-plugin/classes/filter.go Boot publishes classes.NewFilter(db) through app.Publish inside lagoon.OnDatabase app.Publish
statement status verification
No existing route, request or response field, status code, table, migration ID or config key of sm-chat-plugin or sm-forum-plugin changes; the seams are additive (WavePath parity, Phase 31). unresolved automated
statement status verification
sm-moderation-plugin depends on neither sm-chat-plugin nor sm-forum-plugin. unresolved automated
statement status verification
No README, comment or identifier in the eight repos names a consuming application. unresolved judgment
statement status verification
Nothing is pushed, no remote repository is created and no tag is set before the Task 5 go-ahead. unresolved judgment

Phase Goal

ROADMAP Goal (not in user-story format; no story is invented here, see the planning return): sm-demo-app runs every shared Golem15 plugin collected so far in one binary, and its public Nuxt site shows them working: chat and channels with realtime, video calls, presentations, quizzes, journal, FAQ, subscriptions and the rest. Phase 19.4.1 deployed the demo early; this phase adds the chat family to that live instance.

This plan's slice (plan 1 of 6, wave 1, per D-20): the shared plugin release the demo needs before it can require the chat family by tag. Fast-forward the stale sibling checkouts, add the generic pre-save seams to chat and forum (D-18), create sm-moderation-plugin (D-17), fix the go.mod files that break module mode, and, after the user's go-ahead, push and tag all eight repositories.

Decisions taken in this plan (Claude's discretion, recorded)

  • Seam shape (D-18 discretion): a festival "-ing" event fired before the write transaction, mirroring user.Deleting / user.Deactivating in sm-user-plugin. chat gets events.MessageSaving, forum a new events package with events.PostSaving. A listener refuses by returning the plugin's own contracts.Rejection{Field, Message}. Each plugin declares its own type, so forum does not import chat and neither imports moderation. The API maps errors.As(err, &rej) to the existing 422 envelope. Rationale: festival.Bus.Fire already returns the joined listener errors, chat already holds s.bus, forum holds an unused Bus field, and no service gains a new registration method. RESEARCH Pattern 2.
  • Event names: MessageSavingEventName = "golem15.chat.message.saving" and PostSavingEventName = "golem15.forum.post.saving". They are Go-only seams with no PHP counterpart; the doc comments say so.
  • Op values: chat OpCreate = "create" and OpUpdate = "update"; forum OpThread = "thread", OpReply = "reply" and OpUpdate = "update".
  • Moderation lists: two textareas, one entry per line; an enabled switch defaults to true; at most 500 entries of at most 200 characters per list (validated in BeforeValidate). The filter reads the singleton row on every Check and recompiles its matchers only when the stored text changed. RE2's \b is ASCII-only, so word boundaries are built from [^\p{L}\p{N}_] to cover Polish letters.
  • Violation message: Violation{Kind, Match, Message}. Message comes from the plugin's lang files (golem15.moderation::lang.violation.word and .link, EN and PL) in the locale towel.Locale(ctx) carries, resolved through the framework's phrasebook. Without a locale it is English. The chat-family APIs answer in English today, so English is an acceptable fallback.
  • Dependants require existing tags: chatvideo, herald and userfriends require sm-chat-plugin v0.1.3 (the newest tag before this plan), sm-user-plugin v0.1.13 and summercms v0.5.1, the set RESEARCH compiled. That keeps their module-mode check independent of the new chat tag; minimal version selection gives the demo chat v0.1.4.
  • Repository creation: with the go-ahead, Claude creates golem15/sm-moderation-plugin on git.golem15.com with tea when tea login list shows a git.golem15.com login, using the same visibility as sm-sitemap-plugin. Otherwise the user creates it.
  • spec-less probe fallback skipped: phase has no requirement IDs to probe (visible skip).

Artifacts this phase produces (this plan)

  • sm-chat-plugin (v0.1.4): events.MessageSaving, events.MessageSavingEventName, events.OpCreate, events.OpUpdate, contracts.Rejection (Error()), the 422 mapping in writeChatError, smoke test TestMessageSavingTracer (saving_smoke_test.go), a README changelog entry v0.1.4.
  • sm-forum-plugin (v0.1.0): package events (PostSaving, PostSavingEventName, OpThread, OpReply, OpUpdate), contracts.Rejection, the 422 mapping in writeForumError, smoke test TestPostSavingTracer.
  • sm-moderation-plugin (new repo, v0.1.0): plugin golem15.moderation, package moderation, classes.Filter, classes.NewFilter(db *gorm.DB) *Filter, (*Filter).Check(ctx context.Context, text string) (*Violation, error), classes.Match(words, links []string, text string) *Violation, classes.ParseList(text string) []string, classes.Violation{Kind, Match, Message}, classes.KindWord, classes.KindLink, table golem15_moderation_settings (migration 202610280001_create_golem15_moderation_settings), settings item moderation_settings, permission golem15.moderation.manage_settings, config keys golem15.moderation.max_entries and golem15.moderation.max_entry_length, smoke test TestFilterSmoke.
  • go.mod fixes in sm-chatvideo-plugin, sm-herald-plugin and sm-userfriends-plugin.
  • Tags: chat v0.1.4; chatchannels, chatbots, chatvideo, forum, herald, userfriends and moderation v0.1.0 (numbers read from the remote at release time).
  • Full unit tests come in plan 06 (project rule).
Release the chat family so the demo can require it by tag: the D-18 pre-save seams in chat and forum, the D-17 moderation plugin, go.mod hygiene, and eight tags after the user's go-ahead.

Purpose: SC-1 needs sm-demo-app to build from tagged modules (19.4.1 D-03, TestGoModRequiresTags, scripts/check-pins.sh). D-17 and D-18 need the seams and the filter before plan 02 wires them. D-20 makes this plan 01 of six and supersedes D-19's earlier split. Output: commits and, after the go-ahead, pushes and tags in eight plugin repositories. No change in sm-demo-app, vue-demo-app or summercms.go code.

<execution_context> @/.claude/msd-core/workflows/execute-plan.md @/.claude/msd-core/templates/summary.md </execution_context>

@.planning/phases/20-demo-instance-with-every-shared-plugin/20-CONTEXT.md @.planning/phases/20-demo-instance-with-every-shared-plugin/20-RESEARCH.md @.planning/phases/20-demo-instance-with-every-shared-plugin/20-PATTERNS.md @.planning/notes/core-plugins-own-repos.md

Repos (siblings of summercms.go): ../sm-chat-plugin, ../sm-chatchannels-plugin, ../sm-chatbots-plugin (all three behind origin: fast-forward first), ../sm-chatvideo-plugin, ../sm-forum-plugin, ../sm-herald-plugin, ../sm-userfriends-plugin, and the new ../sm-moderation-plugin. Read-only references: ../sm-bm-app/plugins/golem15/{chat,chatchannels,chatbots} (the origin-main trees, for reading only), ../sm-sitemap-plugin (plugin and settings analog), ../sm-demo-app/plugins/golem15/user/classes/events.go (the "-ing" event analog).

Rules: no co-author tags in commits (user instruction overrides any attribution default); stage files by explicit path, never git add -A; one logical change per commit; nothing pushed, created or tagged before Task 5. Verify commands run from the framework root and address siblings with go -C ../<repo>. Plugin repos with a tracked go.work resolve their siblings through it (the seam-carrying ../sm-chat-plugin included). If the Docker socket is denied, run the Docker tests through sudo -u golem (CLAUDE.md).

chat (origin main 51c9e17 = v0.1.3, same tree as ../sm-bm-app/plugins/golem15/chat): - `classes.Service` fields `bus *festival.Bus` (from `Options.Bus`); `SendMessageWith(ctx, in SendInput) (*models.Message, error)` validates metadata, loads the conversation, checks `canSend`, trims content, returns `ErrEmptyMessage` when content and attachments are empty, then opens `lagoon.Transaction` and fires `events.MessageCreated` inside it (classes/service.go:287-345). `SendMessage` and `ReplyTo` (classes/attachments.go:218) funnel into it. - `EditMessage(ctx, actorID, messageID uint, content string) (*models.Message, error)` in classes/writes.go:248, after `CanEditMessage` (writes.go:202). - events/events.go: `MessageEvent{MessageID, ConversationID, ActorID uint; RootID *uint; Tx *gorm.DB}`, `MessageCreated`, `MessageUpdated`, `MessageDeleted`, consts `MessageCreatedEventName` etc.; the package doc says every event fires inside the transaction. - api/errors.go: `writeValidation(w, map[string][]string)`, `writeChatError(w, what, err)` (switch over errors.Is, default 500). - Test helpers: harness_test.go `bootChat`, `(*chatEnv).user`, `.count`, `.memory`, `.conversation(t, createdBy, typ, alias, contextID, participants...)`; http_tracer_test.go `bootWeb`, `(*webEnv).frontendToken`, `.call(t, method, path, token, body)`, `decodeObject`. forum (../sm-forum-plugin, origin main 2779341): - `classes.ForumService{bus *festival.Bus}` built in boot.go `bootService` with `Bus: app.Events`; `CreateThread(ctx, actorID, contextType, contextID, categoryID, title, body)` renders at forum_service.go:281, `Reply(...)` at :330, `EditPost(ctx, actorID, contextType, contextID, postID, body)` in classes/lifecycle.go:217. No `Fire(` call exists in the plugin today. - api/errors.go: `writeValidation`, `writeForumError` (ErrForbidden/ErrNotFound 404, ErrTitleRequired/ErrBodyRequired 422). - Test helpers: harness_test.go `bootForum`, `.user`, `.count`; http_tracer_test.go `bootWeb`, `.frontendToken`, `.call`. festival (framework): `(*Bus).Listen[T any](owner string, fn func(context.Context, T) error)`, `(*Bus).Fire[T any](ctx, event T) error` returns errors.Join of listener errors (callers use errors.As). sitemap analog: plugin.go (embed config, `pact.HasConfig/HasMigrations/HasModels`), admin.go (`Settings() []pact.SettingsItem` with Code, Label, Description, Category, Icon, Permissions, Form, NewModel; `AdminFS`, `LangFS`), admin_permissions.go (`Permissions() []pact.Permission`), models/settings.go (singleton row id 1, `*string` columns, `BeforeValidate` with a lang-key error), models/settings/fields.yaml, updates/202610110002_create_golem15_sitemap_settings.go (CREATE TABLE plus INSERT id 1), go.mod replace `git.golem15.com/golem15/summercms => ../summercms.go`, tracked go.work. go.mod today: chatvideo requires chat v0.0.0 and replaces chat and user with sibling paths; herald replaces user with ../fonoteka.go/plugins/golem15/user; userfriends requires chat pseudo-version v0.0.0-20261017200243-4d0e764ca443. Task 1: Tracer: a rejecting MessageSaving listener turns a chat send into the existing 422 envelope and nothing is stored D-18: the seam becomes a public plugin contract other consumers can start using; changing its shape later touches every listener. `git -C ../sm--plugin status --porcelain` prints nothing for chat, chatchannels, chatbots, chatvideo, forum, herald and userfriends; `docker info` exits 0. ../sm-chat-plugin/events/events.go, ../sm-chat-plugin/contracts/rejection.go, ../sm-chat-plugin/classes/service.go, ../sm-chat-plugin/classes/writes.go, ../sm-chat-plugin/api/errors.go, ../sm-chat-plugin/saving_smoke_test.go, ../sm-chat-plugin/README.md ../sm-chat-plugin/classes/service.go (SendMessageWith, Options.Bus), ../sm-chat-plugin/classes/writes.go (EditMessage, CanEditMessage), ../sm-chat-plugin/classes/attachments.go (ReplyTo), ../sm-chat-plugin/events/events.go, ../sm-chat-plugin/api/errors.go, ../sm-chat-plugin/api/messages.go and api/replies.go, ../sm-chat-plugin/http_tracer_test.go and harness_test.go, ../sm-chat-plugin/php_method_map_test.go, ../sm-chat-plugin/README.md, ../sm-demo-app/plugins/golem15/user/classes/events.go (DeactivatingEvent doc style), modules/festival/bus.go, 20-RESEARCH.md (Pattern 2, Pitfall 1), 20-PATTERNS.md (Chat / forum pre-save seam) Per D-18 and D-20; wire one path end to end: listener, service, API, HTTP response, database unchanged.
  1. Fast-forward every sibling first (RESEARCH Pitfall 1): for chat, chatchannels, chatbots, chatvideo, forum, herald and userfriends run git -C ../<repo> pull --ff-only and confirm git -C ../<repo> rev-parse HEAD equals the hash git -C ../<repo> ls-remote origin refs/heads/main prints (use the default branch each repo tracks). Record both hashes per repo for the SUMMARY. A non-fast-forward stops the task.
  2. events/events.go: keep the three existing events untouched. Add MessageSavingEventName = "golem15.chat.message.saving" on its own line and a MessageSaving struct with ConversationID, ActorID and MessageID uint (MessageID is 0 on create), RootID *uint, Content string and Op string, plus the constants OpCreate = "create" and OpUpdate = "update". MessageSaving carries no Tx because it fires before the transaction. Rewrite the package doc: the three message events fire inside the transaction after the save; MessageSaving fires before it, has no PHP counterpart, and a listener error aborts the write; a listener refuses with contracts.Rejection.
  3. contracts/rejection.go: type Rejection struct { Field, Message string } with a value-receiver Error() string returning "golem15.chat: rejected " + Field + ": " + Message. The doc comment explains that listeners return the value (not a pointer) and callers match it with errors.As, because Fire joins listener errors.
  4. classes/service.go SendMessageWith: after the ErrEmptyMessage check and before lagoon.Transaction, when s.bus != nil, fire &events.MessageSaving{Op: events.OpCreate, ConversationID, ActorID: senderID, RootID: rootID, Content: content} (the trimmed content) and return nil, err on error. classes/writes.go EditMessage: after CanEditMessage allows the edit and the new content is validated, before its transaction, fire the same event with Op: events.OpUpdate and the MessageID. No other line of either method changes.
  5. api/errors.go writeChatError: before the existing switch, declare var rej contracts.Rejection and, when errors.As(err, &rej), call writeValidation(w, map[string][]string{field: {rej.Message}}) with field = rej.Field, or "content" when Field is empty, then return. The other branches stay byte-identical.
  6. saving_smoke_test.go TestMessageSavingTracer (Docker; skips under -short like the other HTTP tests): boot with bootWeb; register on the app's event bus a *events.MessageSaving listener returning contracts.Rejection{Field: "content", Message: "not allowed"} when Content contains the word "blocked"; create a group conversation with two participants through the harness; then
    • POST /_chat/api/v1/conversations/{id}/messages with content "this is blocked": 422, body errors.content equals ["not allowed"], and golem15_chat_messages has 0 rows;
    • POST the content "hello": 201, 1 row;
    • PUT /_chat/api/v1/messages/{id} with "blocked edit": 422, and the stored content is still "hello";
    • POST /_chat/api/v1/messages/{id}/replies with "blocked reply": 422, and the row count is still 1.
  7. README.md: in Features and API reference, add MessageSaving (when it fires, no Tx, Op values), MessageSavingEventName, OpCreate, OpUpdate and contracts.Rejection, with a neutral example host listener (acme). Add a changelog entry "v0.1.4: pre-save MessageSaving event and Rejection (additive; no listener means no change)". Name no consuming application.

Commit in ../sm-chat-plugin by path (feat: pre-save MessageSaving event and Rejection), README in the same commit. Do not push or tag. go -C ../sm-chat-plugin vet ./... && go -C ../sm-chat-plugin test -count=1 -short ./... && go -C ../sm-chat-plugin test -count=1 -run '^TestMessageSavingTracer$' -v . 2>&1 | grep -q -- '^--- PASS: TestMessageSavingTracer' <fails_when>Non-zero exit: vet or the short suite red (php_method_map or golden tests broken by the change), or no "--- PASS: TestMessageSavingTracer" line (Docker unavailable so it skipped, a 201 where 422 was expected, or a stored row after a refusal).</fails_when> <acceptance_criteria> - go -C ../sm-chat-plugin test -count=1 ./... (with Docker) passes, including the unchanged php_method_map_test.go and golden_test.go. - git -C ../sm-chat-plugin diff HEAD~1 --stat -- php_method_map_test.go golden_test.go testdata prints nothing. - grep -c 'MessageSavingEventName = "golem15.chat.message.saving"' ../sm-chat-plugin/events/events.go prints 1. - grep -c 'errors.As(err, &rej)' ../sm-chat-plugin/api/errors.go prints 1. - grep -c 'v0.1.4' ../sm-chat-plugin/README.md prints at least 1. - The SUMMARY records the before and after HEAD of all seven siblings, and each after-HEAD equals origin's default branch. </acceptance_criteria> A host can refuse a chat message before it is stored, the client gets the existing 422 envelope, and without a listener chat behaves byte-identically.

Task 2: The forum gets the same seam: PostSaving before render on thread, reply and edit D-18: a new public event package and Rejection type in a WavePath port-target plugin; later consumers depend on the field names. ../sm-forum-plugin/events/events.go, ../sm-forum-plugin/contracts/rejection.go, ../sm-forum-plugin/classes/forum_service.go, ../sm-forum-plugin/classes/lifecycle.go, ../sm-forum-plugin/api/errors.go, ../sm-forum-plugin/saving_smoke_test.go, ../sm-forum-plugin/README.md ../sm-forum-plugin/classes/forum_service.go (Options, New, CreateThread, Reply), ../sm-forum-plugin/classes/lifecycle.go (EditPost), ../sm-forum-plugin/boot.go (bootService passes app.Events), ../sm-forum-plugin/api/errors.go, ../sm-forum-plugin/api/threads.go and api/posts.go, ../sm-forum-plugin/http_tracer_test.go, harness_test.go and fixture_plugin_test.go (test access resolver), ../sm-forum-plugin/php_method_map_test.go, ../sm-forum-plugin/README.md, ../sm-chat-plugin/events/events.go and contracts/rejection.go (Task 1, for the shape) Per D-18.
  • New package events (events/events.go):
    • PostSavingEventName = "golem15.forum.post.saving";
    • PostSaving with ContextType string, ContextID, ActorID, ThreadID and PostID uint, Title, Body and Op string;
    • constants OpThread = "thread" (ThreadID 0, Title set), OpReply = "reply" and OpUpdate = "update".
    • The package doc says forum fires no post-save events, PostSaving is a Go-only seam fired before render and persistence, and a listener error aborts the write.
  • contracts/rejection.go: the same shape as chat's, with "golem15.forum: rejected " in Error().
  • ForumService, all guarded by s.bus != nil, firing after the access and required-field checks and before breakwater.Render, returning the error unchanged:
    • CreateThread fires PostSaving with OpThread, the trimmed title and the body;
    • Reply fires it with OpReply, the ThreadID and the body;
    • EditPost (lifecycle.go) fires it with OpUpdate, the PostID, its ThreadID and the body.
  • api/errors.go writeForumError: before the switch, errors.As(err, &rej) writes 422 {rej.Field: [rej.Message]}, with field "body" when Field is empty.
  • saving_smoke_test.go TestPostSavingTracer (Docker): boot through bootWeb with the fixture resolver that allows posting; register a PostSaving listener rejecting Title or Body containing "blocked" (Field "title" or "body"). Then:
    • POST a thread whose title holds the word: 422 errors.title, no thread and no post row;
    • a clean thread: 201;
    • a reply whose body holds the word: 422 errors.body;
    • PUT the first post with the word: 422, and content_html is unchanged.
  • README: add Features "Pre-save seam" and the API reference rows (events.PostSaving, PostSavingEventName, Op constants, contracts.Rejection), and correct the Overview so it says forum fires only this pre-save event. Add a changelog line "v0.1.0: first tag; adds the pre-save PostSaving seam". Name no application.

Commit in ../sm-forum-plugin by path (feat: pre-save PostSaving event and Rejection). Do not push or tag. go -C ../sm-forum-plugin vet ./... && go -C ../sm-forum-plugin test -count=1 -short ./... && go -C ../sm-forum-plugin test -count=1 -run '^TestPostSavingTracer$' -v . 2>&1 | grep -q -- '^--- PASS: TestPostSavingTracer' <fails_when>Non-zero exit: vet or the short suite red, or no "--- PASS: TestPostSavingTracer" line (skipped without Docker, a refused write that still stored a row, or the wrong 422 field).</fails_when> <acceptance_criteria> - go -C ../sm-forum-plugin test -count=1 ./... passes with Docker, php_method_map_test.go and golden_test.go unedited (git -C ../sm-forum-plugin diff HEAD~1 --stat -- php_method_map_test.go golden_test.go prints nothing). - grep -rn 'sm-chat-plugin' ../sm-forum-plugin/go.mod ../sm-forum-plugin/events ../sm-forum-plugin/contracts prints nothing. - grep -c 'PostSaving{' ../sm-forum-plugin/classes/forum_service.go prints 2 and grep -c 'PostSaving{' ../sm-forum-plugin/classes/lifecycle.go prints 1. </acceptance_criteria> Forum threads, replies and edits can be refused before render and storage with the existing 422 envelope; without a listener nothing changes.

Task 3: New shared plugin sm-moderation-plugin: banned words and links, editable in admin settings, published as a Filter ../sm-moderation-plugin/.gitignore, ../sm-moderation-plugin/go.mod, ../sm-moderation-plugin/go.sum, ../sm-moderation-plugin/go.work, ../sm-moderation-plugin/plugin.go, ../sm-moderation-plugin/admin.go, ../sm-moderation-plugin/admin_permissions.go, ../sm-moderation-plugin/logger.go, ../sm-moderation-plugin/classes/filter.go, ../sm-moderation-plugin/classes/filter_smoke_test.go, ../sm-moderation-plugin/models/settings.go, ../sm-moderation-plugin/models/registry.go, ../sm-moderation-plugin/models/settings/fields.yaml, ../sm-moderation-plugin/updates/202610280001_create_golem15_moderation_settings.go, ../sm-moderation-plugin/updates/registry.go, ../sm-moderation-plugin/lang/en/lang.yaml, ../sm-moderation-plugin/lang/pl/lang.yaml, ../sm-moderation-plugin/config/config.yaml, ../sm-moderation-plugin/README.md ../sm-sitemap-plugin/plugin.go, admin.go, admin_permissions.go, logger.go, models/settings.go, models/registry.go, models/settings/fields.yaml, updates/202610110002_create_golem15_sitemap_settings.go, updates/registry.go, lang/en/lang.yaml, config/config.yaml, go.mod, go.work, README.md (the whole plugin layout), modules/phrasebook/README.md and modules/towel/README.md (locale lookup), `summer help make:plugin` (scaffold option), .planning/notes/core-plugins-own-repos.md, 20-PATTERNS.md (sm-moderation-plugin) Per D-17. Create the repository at /media/nvme/dev/golem15/summercms.io/summercms/sm-moderation-plugin with `git init -b main`. Add no remote yet. Start from `summer make:plugin golem15.moderation` if it emits a standalone module layout, otherwise copy the sitemap layout. Module `git.golem15.com/golem15/sm-moderation-plugin`, package `moderation`, plugin ID `golem15.moderation`, `Requires()` nil, display name Moderation / Moderacja. Standard library plus gorm, gormigrate and framework modules only.
  • go.mod: go 1.27.0, require git.golem15.com/golem15/summercms v0.5.1 plus gorm and gormigrate at the versions sitemap's go.mod uses, and replace git.golem15.com/golem15/summercms => ../summercms.go. Run go mod tidy. Track a go.work with use . and the same replace, as sitemap does.
  • plugin.go: the interface assertions (party.Plugin, pact.HasConfig, pact.HasMigrations, pact.HasModels) and //go:embed config. Register keeps the app. Boot calls lagoon.OnDatabase and publishes classes.NewFilter(db) with app.Publish. The package doc says the plugin is a content filter other plugins' hosts wire into their pre-save seams, and that it imports no content plugin.
  • config/config.yaml: max_entries: 500, max_entry_length: 200.
  • models/settings.go: Settings singleton on golem15_moderation_settings (ID uint, Enabled bool, BannedWords *string, BannedLinks *string). BeforeValidate refuses:
    • a list longer than max_entries (lang key golem15.moderation::lang.errors.too_many);
    • an entry longer than max_entry_length (errors.too_long);
    • a link entry that is neither a host name nor an http(s) URL (errors.link). models/registry.go All().
  • models/settings/fields.yaml: enabled (switch), banned_words (textarea, comment "one word or phrase per line"), banned_links (textarea, comment "one domain or URL per line; subdomains match"), with the sitemap header comment block.
  • updates/202610280001_create_golem15_moderation_settings.go: CREATE TABLE IF NOT EXISTS golem15_moderation_settings (id INTEGER PRIMARY KEY, enabled BOOLEAN NOT NULL DEFAULT TRUE, banned_words TEXT NULL, banned_links TEXT NULL) and INSERT INTO golem15_moderation_settings (id) VALUES (1) ON CONFLICT (id) DO NOTHING. Rollback drops the table. updates/registry.go All().
  • admin.go: Settings() returns item Code moderation_settings (lang keys for label, description and category, Icon "shield", Permissions [golem15.moderation.manage_settings], Form models/settings/fields.yaml, NewModel), plus AdminFS and LangFS, with the sitemap assertions (AdminAssets, HasSettings, HasLang). admin_permissions.go declares the permission on the role list sitemap uses.
  • lang/en and lang/pl: plugin name, settings label, description and category, field labels and comments, errors.*, violation.word ("The text contains a word that is not allowed." / "Tekst zawiera niedozwolone słowo.") and violation.link ("The text contains a link that is not allowed." / "Tekst zawiera niedozwolony link.").
  • classes/filter.go:
    • KindWord = "word", KindLink = "link"; Violation{Kind, Match, Message string};
    • ParseList(text string) []string splits lines, trims them, lowercases them and drops empty lines and duplicates;
    • Match(words, links []string, text string) *Violation is pure and returns the first violation, words before links:
      • a word or phrase matches case-insensitively between non-letter, non-digit boundaries (built from [^\p{L}\p{N}_], start or end of text) with regexp.QuoteMeta;
      • a link entry that is a host (example.com) matches any host in the text equal to it or ending in "." plus it: http(s) URLs, www. prefixes and bare domains (labels of letters, digits and hyphens with at least one dot);
      • an entry with a path matches a URL whose host and path start with it.
    • NewFilter(db) *Filter. (*Filter).Check(ctx, text) (*Violation, error) reads the singleton row, returns nil when Enabled is false, recompiles the matchers only when the stored text differs from the cached text (guard the cache with a sync.Mutex), and fills Message from the lang phrase for towel.Locale(ctx) through the framework phrasebook, falling back to the English text.
  • classes/filter_smoke_test.go TestFilterSmoke (pure, no Docker): "Spam here" against the word spam gives a word violation; "spamming" gives none; "Kup TANIO teraz" against the phrase "kup tanio" gives a word violation; "visit https://www.bad.example/x" and "bad.example" against the link bad.example give link violations; "good.example" gives none.
  • README.md in the standard plugin structure:
    • H1, one-sentence summary, import line, a **Name:** beach mnemonic, Overview, Features, Usage, API reference, Configuration (the two keys), Dependencies, Testing;
    • Usage shows a neutral host (acme) wiring Check into another plugin's pre-save event without importing it here.

Commit in ../sm-moderation-plugin (feat: golem15.moderation banned word and link filter). Do not create a remote, push or tag. go -C ../sm-moderation-plugin vet ./... && go -C ../sm-moderation-plugin test -count=1 -short ./... && go -C ../sm-moderation-plugin test -count=1 -run '^TestFilterSmoke$' -v ./classes 2>&1 | grep -q -- '^--- PASS: TestFilterSmoke' <fails_when>Non-zero exit: the module does not build or vet, the short suite fails, or no "--- PASS: TestFilterSmoke" line (a boundary or host rule wrong).</fails_when> <acceptance_criteria> - go -C ../sm-moderation-plugin list -deps ./... | grep -cE 'sm-(chat|forum)-plugin' prints 0. - grep -c 'golem15_moderation_settings' ../sm-moderation-plugin/updates/202610280001_create_golem15_moderation_settings.go prints at least 2. - grep -c 'golem15.moderation.manage_settings' ../sm-moderation-plugin/admin_permissions.go prints at least 1. - grep -c '^\*\*Name:\*\*' ../sm-moderation-plugin/README.md prints 1. - git -C ../sm-moderation-plugin remote prints nothing. </acceptance_criteria> A shared, chat-agnostic moderation plugin exists locally: admins edit banned words and links in settings, and any host can call Filter.Check from a pre-save seam.

Task 4: Module-mode hygiene: chatvideo, herald and userfriends require tags, and the whole family builds and tests ../sm-chatvideo-plugin/go.mod, ../sm-chatvideo-plugin/go.sum, ../sm-chatvideo-plugin/README.md, ../sm-herald-plugin/go.mod, ../sm-herald-plugin/go.sum, ../sm-herald-plugin/README.md, ../sm-userfriends-plugin/go.mod, ../sm-userfriends-plugin/go.sum, ../sm-userfriends-plugin/README.md ../sm-chatvideo-plugin/go.mod and go.work, ../sm-herald-plugin/go.mod and go.work, ../sm-userfriends-plugin/go.mod and go.work, ../sm-chatchannels-plugin/go.mod and ../sm-chatbots-plugin/go.mod (after the Task 1 fast-forward), ../sm-bm-app/plugins/golem15/chatbots/go.mod (the "drop sibling replaces" analog), each README's Dependencies section, 20-RESEARCH.md (Repo State and Tagging, Pitfall 2) Per SC-1 and RESEARCH Pitfall 2. With `GOWORK=off GOPRIVATE=git.golem15.com/*`, edit each go.mod: - sm-chatvideo-plugin: delete the sm-chat-plugin and sm-user-plugin replace lines. Require `git.golem15.com/golem15/sm-chat-plugin v0.1.3`, `sm-user-plugin v0.1.13` and `summercms v0.5.1`. Keep `replace git.golem15.com/golem15/summercms => ../summercms.go`. - sm-herald-plugin: delete the sm-user-plugin replace. Require sm-user-plugin v0.1.13 and summercms v0.5.1. - sm-userfriends-plugin: replace the chat pseudo-version with v0.1.3. Require sm-user-plugin v0.1.13 and summercms v0.5.1. - sm-chatchannels-plugin and sm-chatbots-plugin (fast-forwarded in Task 1): confirm their go.mod holds no replace other than the framework one and only tag requires. If either does not, fix it the same way and add it to this task's commits. Run `go mod tidy` in each changed repo (GOWORK=off). The tracked go.work files stay: they are development conveniences and module consumers ignore them. Update each changed README's Dependencies section with the required versions and add a changelog line "v0.1.0: first tag; requires tagged chat, user and SummerCMS modules" where the README keeps a changelog.

Then verify the family:

  • all eight repos (chat, chatchannels, chatbots, chatvideo, forum, herald, userfriends, moderation) pass go vet ./... and go test -count=1 -short ./... through their go.work;
  • chatchannels, chatbots, chatvideo, herald and userfriends pass GOWORK=off go build ./..., which resolves chat v0.1.3 and user v0.1.13 from git.golem15.com and proves no sibling path is needed. Grep the changed files of all eight repos for consuming application names (the sm-*-app repository names next to summercms.go, and their vendor prefixes) and remove any hit in the files this plan changed.

Commit per repo by path (chore: require tagged chat, user and SummerCMS modules; drop sibling replaces). Do not push or tag. for r in sm-chat-plugin sm-chatchannels-plugin sm-chatbots-plugin sm-chatvideo-plugin sm-forum-plugin sm-herald-plugin sm-userfriends-plugin sm-moderation-plugin; do go -C ../$r vet ./... && go -C ../$r test -count=1 -short ./... || exit 1; done && for r in sm-chatchannels-plugin sm-chatbots-plugin sm-chatvideo-plugin sm-herald-plugin sm-userfriends-plugin; do GOWORK=off GOPRIVATE='git.golem15.com/*' go -C ../$r build ./... || exit 1; done <fails_when>Non-zero exit: any repo fails vet or its short suite, or a GOWORK=off build fails (for example "unknown revision v0.0.0" or a sibling replace path that no longer resolves).</fails_when> <acceptance_criteria> - grep -cE '^replace .*=> \.\./(sm-|fonoteka)' ../sm-chatvideo-plugin/go.mod ../sm-herald-plugin/go.mod ../sm-userfriends-plugin/go.mod prints 0 for each file. - grep -c 'v0.0.0' ../sm-chatvideo-plugin/go.mod ../sm-userfriends-plugin/go.mod prints 0 for each file. - grep -c 'sm-chat-plugin v0.1.3' ../sm-chatvideo-plugin/go.mod ../sm-userfriends-plugin/go.mod prints 1 for each file. - git -C ../sm-<repo> status --porcelain prints nothing for all eight repos after the commits. </acceptance_criteria> Every chat-family module resolves its dependencies by tag, so a demo build without go.work can require them.

Task 5: Go-ahead for the one-way release: create sm-moderation-plugin on git.golem15.com, push eight repositories and tag them The release table Claude prints before asking, one row per repository: current remote tags (`git ls-remote --tags origin`), the next free tag, the commit it will sit on, the commits it adds since the last tag, and why (seam, first tag, go.mod fix, new repo). Also whether `tea login list` shows a git.golem15.com login, and the visibility of sm-sitemap-plugin. - The user chose one option and it is recorded in the SUMMARY. With "release", git.golem15.com/golem15/sm-moderation-plugin exists (`git ls-remote git@git.golem15.com:golem15/sm-moderation-plugin.git` exits 0) before Task 6 pushes. Create the sm-moderation-plugin repository, push the commits of this plan and set the eight tags now? A pushed Go module tag is cached by module proxies and can never point anywhere else (one-way, as 19.4.1 D-03). Tags freeze exactly the commits Tasks 1-4 verified. chat v0.1.4 is a patch: the seam is additive and WavePath's parity tests stay green (D-18). Plan 02 cannot mount the chat family by tag until this runs. Creating a repository on git.golem15.com and pushing need your go-ahead (CLAUDE.md). Create the repository, push and tag Plan 02 can mount all eight plugins by tag; other applications can adopt the seams and the filter. The tags are permanent; a mistake needs a new patch tag, not a moved tag. Hold Nothing permanent happens. Plan 02 and every later plan are blocked; the demo cannot require the chat family. For "release": if Claude reported no tea login for git.golem15.com, create the repository golem15/sm-moderation-plugin (empty, same visibility as sm-sitemap-plugin, default branch main) in the git.golem15.com web UI first, then reply. Do not paste tokens into the chat. Reply "release" (add "repo ready" if you created the repository yourself) or "hold". Task 6: Release: push, tag and prove the eight tags resolve in module mode Pushed module tags are cached by proxies and every consumer's go.sum; they can only be superseded, never moved. Task 5 resolved with "release"; `git ls-remote git@git.golem15.com:golem15/sm-moderation-plugin.git` exits 0 or `tea login list` lists git.golem15.com. ../sm-moderation-plugin/README.md The Task 5 release table, each repository's README changelog, .planning/notes/core-plugins-own-repos.md Per SC-1 and D-17/D-18. 1. If the repository does not exist yet, create it with `tea repo create --name sm-moderation-plugin --owner golem15` at sm-sitemap-plugin's visibility. Then `git -C ../sm-moderation-plugin remote add origin git@git.golem15.com:golem15/sm-moderation-plugin.git` and push main with upstream. 2. Push the default branch of chat, forum, chatvideo, herald and userfriends (and chatchannels or chatbots only if Task 4 committed there). No force-push. 3. Read the next free tag from `git ls-remote --tags origin` per repository: chat the next v0.1.x patch (v0.1.4 expected), the others v0.1.0 unless taken. Create annotated tags (`git tag -a -m ""`) on the HEADs Tasks 1-4 verified, chat first. Push each tag. Confirm `git ls-remote origin refs/tags/^{}` equals the local HEAD. 4. If the moderation README says no tag exists yet, fix it in a commit before tagging that repository, never after. 5. Module-mode proof: in a fresh `mktemp -d` directory, `go mod init example.invalid/familycheck`, require all eight modules at their new tags plus `git.golem15.com/golem15/summercms v0.5.1`, write a main.go that blank-imports the eight plugin packages, then run `GOWORK=off GOPRIVATE=git.golem15.com/* GOFLAGS=-mod=mod go build ./...`. Delete the directory afterwards. The SUMMARY records every tag with its commit hash for plan 02. for r in sm-chat-plugin sm-chatchannels-plugin sm-chatbots-plugin sm-chatvideo-plugin sm-forum-plugin sm-herald-plugin sm-userfriends-plugin sm-moderation-plugin; do t=$(git -C ../$r describe --tags --exact-match HEAD) && [ "$(git -C ../$r ls-remote origin "refs/tags/$t^{}" | cut -f1)" = "$(git -C ../$r rev-parse HEAD)" ] || exit 1; done Non-zero exit: a repository HEAD carries no tag (describe fails), or the remote tag is missing or points at a different commit than the local HEAD. - `git -C ../sm-chat-plugin describe --tags --exact-match HEAD` prints a v0.1.x tag at least v0.1.4. - The scratch module build printed no error, and the SUMMARY lists the eight tags with commit hashes. - `git -C ../sm- status --porcelain` prints nothing in all eight repositories. All eight chat-family modules are on git.golem15.com at verified tags and resolve together without go.work.

<threat_model>

Trust Boundaries

Boundary Description
chat/forum HTTP clients to the plugin APIs message and post bodies are untrusted input; the seam runs on them before storage
host listeners to plugin services host code decides refusals; a listener error must not leak internals
admin settings to the filter administrators edit the lists that every message is matched against
build machine to git.golem15.com and module proxies tags become immutable inputs of every consumer

STRIDE Threat Register

Threat ID Category Component Severity Disposition Mitigation Plan
T-20-01 Tampering chat write paths that skip the seam high mitigate MessageSaving fires in SendMessageWith (SendMessage, replies and ReplyTo funnel into it) and EditMessage; TestMessageSavingTracer covers send, reply and edit; plan 06 adds the full matrix
T-20-02 Information disclosure listener errors surfacing in API bodies medium mitigate only contracts.Rejection maps to 422 with its own Field and Message; any other listener error keeps the existing opaque 500 path of writeChatError and writeForumError
T-20-03 Denial of service filter matching cost medium mitigate RE2 linear-time regexps from QuoteMeta'd entries; at most 500 entries of at most 200 characters per list (BeforeValidate); matchers compiled once per list version
T-20-04 Elevation of privilege moderation settings screen medium mitigate settings item behind the permission golem15.moderation.manage_settings, granted to the same role as sitemap settings
T-20-05 Tampering one-way module tags medium mitigate tags only on HEADs that passed vet and tests in Tasks 1-4; next free number read from the remote; go-ahead at Task 5; ls-remote check and a GOWORK=off scratch build after pushing
T-20-SC Tampering npm/pip/cargo installs high mitigate no package-manager install: Go modules are the project's own tagged repositories plus gorm and gormigrate at versions already in sm-sitemap-plugin's go.sum (GOPRIVATE, go.sum committed)
</threat_model>
- Task 1: chat seam tracer green, chat parity tests unchanged, seven siblings at origin HEAD. - Task 2: forum seam tracer green, forum parity tests unchanged. - Task 3: moderation plugin builds, filter smoke green, no dependency on chat or forum. - Task 4: all eight repositories vet and test; five chat dependants build with GOWORK=off. - Task 5: go-ahead recorded. - Task 6: eight tags on origin equal to the verified HEADs; the scratch module builds them together.

<success_criteria> The chat family and the moderation plugin are released by tag (SC-1 prerequisite), with the D-18 seams additive and parity-safe and the D-17 filter shared and chat-agnostic. </success_criteria>

Create `.planning/phases/20-demo-instance-with-every-shared-plugin/20-01-SUMMARY.md` when done: per repository the before and after HEAD, the tag and its commit, the go.mod changes, how the moderation repository was created, and the checkpoint answer.