Phase 35 (mail templates/layouts editor) was reviewed at standard depth across postcard, cabana mail screens/routes, and the admin SPA mail editor. Security posture is solid: permission gates, `interactiveOnly` test-send, recipient-key refusal, rate limiting, sandboxed preview iframe (`sandbox=""`), HTML/CSS unsafe-tag checks, colour validation, and image upload limits. Draft validation runs inside the form save transaction (`FormAfterUpdate`), so invalid overrides roll back. Findings below are correctness/UX gaps, not blockers.
## Narrative Findings (AI reviewer)
## Warnings
### WR-01: Layout status filter hides every database-only layout
**File:**`modules/cabana/mail_admin.go:682-688`
**Issue:**`mailStatusScope` treats "customized" and "outdated" as file-backed only (`is_custom AND source IS NOT NULL`), while "not_customized" is `NOT is_custom`. Database-only layouts have `source IS NULL` and `is_custom = true`, so they match none of the three values. Choosing any status on the layouts list silently drops all custom layouts.
**Fix:** Include database-only layouts under customized (and keep outdated file-backed-only), e.g.:
```go
casemailStatusCustomized:
returndb.Where(table+".is_custom")
casemailStatusNotCustomized:
returndb.Where("NOT "+table+".is_custom")
casemailStatusOutdated:
returndb.Where(table+".is_custom AND "+table+".source IS NOT NULL AND "+table+".base_hash IS DISTINCT FROM "+table+".file_hash")
```
### WR-02: Unknown `filterStatus` value leaves the query unfiltered
**File:**`modules/cabana/mail_admin.go:677-689`
**Issue:** When `name == mailFilterStatus` but `value` is not one of the three known statuses, the function returns `db` unchanged (all rows). Wrong scope names correctly match nothing (`1 = 0`); wrong values do the opposite.
**Fix:**
```go
switchvalue{
casemailStatusCustomized:
// ...
casemailStatusNotCustomized:
// ...
casemailStatusOutdated:
// ...
default:
returndb.Where("1 = 0")
}
```
### WR-03: Mail image upload errors ignore field-level validation details
**Issue:** Upload failures from the API use `ValidationError` details shaped as `{ file: ["…"] }` (`mail_routes.go` via `writeCRUDError`). The picker reads `details.message`, which is absent, so operators usually see the generic top-level `"Validation failed"` instead of the attach limit/type message.
**Fix:** Prefer the first string under `details.file` (or any field array), then fall back:
**Issue:** For `mode === 'partial'` (and `layout`), `draftEmpty` only inspects `content_html`. A text-only partial draft (empty HTML, non-empty `content_text`) shows the empty state and disables test-send on the text tab, even though the server draft can render text.
**Fix:** Treat the draft as non-empty when any relevant content field is present:
**Issue:** When the draft becomes empty, `hasRender` / `html` / `text` / `subject` are left as-is. While empty the UI shows the empty state, but the first keystroke after that briefly shows the previous render until the debounced preview returns.
**Fix:** Clear `hasRender`, `html`, `text`, and `subject` in the `draftEmpty` early-return paths (watch + `renderPreview`).
### IN-02: Color picker swatch shows last valid colour when text is empty
**Issue:** An empty model value still drives the native swatch from `lastValid` (default `#ffffff`), which can look like a chosen white while the field is "not set" and the server treats empty as the brand default.
**Fix:** When `text` is empty, disable the swatch or show a neutral placeholder instead of `lastValid`.
### IN-03: ListExtendRecords mutates stored locale/source pointers for display
**Issue:** List hooks rewrite `Locale` / `Source` in place with translated display labels. Safe for the list JSON path today, but fragile if those model instances are reused for writes or exports.
**Fix:** Prefer a DTO / computed column for display (as other list extend examples do with unstored badge fields) instead of mutating override/index columns.
---
_Reviewed: 2026-11-13T13:39:18Z_
_Reviewer: the agent (msd-code-reviewer, generic-agent workaround)_
name: Open Settings → Mail → Mail templates in a running admin SPA with a plugin that registers HasMailTemplates (e.g. user plugin templates).
expected: |
All registered templates appear; customize subject/body/layout; save; Reset to file version restores file content; drift callout appears after file change.
awaiting: user response
## Tests
### 1. Open Settings → Mail → Mail templates in a running admin SPA with a plugin that registers HasMailTemplates (e.g. user plugin templates).
expected: All registered templates appear; customize subject/body/layout; save; Reset to file version restores file content; drift callout appears after file change.
result: [pending]
### 2. Edit a layout in codeeditor (HTML/text/CSS tabs); insert an image from the library; save Branding colours and logo; preview HTML/plain text; Send test to me.
expected: CodeMirror highlighting/focus feels correct; inserted URL is absolute server URL; preview iframe is sandboxed server HTML; test mail arrives only at the signed-in admin address (Mailpit).
result: [pending]
### 3. Confirm judgment-tier prohibition: postcard imports modules/lagoon/attach for AbsolutePublicURL.
expected: Accept as intentional (D-24 / 35-01 SUMMARY threat_flag dependency-surface) or request a follow-up to move AbsolutePublicURL out of lagoon.
- finding: "Layout status filter hides database-only layouts (WR-01)"
category: other
reason: "35-REVIEW.md WR-01 — filter customized/outdated require source IS NOT NULL; custom layouts vanish under any status value. Does not break default unfiltered list or editability must-haves."
evidence_status: "code present; advisory from code review"
- finding: "Unknown filterStatus value leaves query unfiltered (WR-02)"
category: other
reason: "35-REVIEW.md WR-02 — soft filter hygiene; wrong values should match nothing."
evidence_status: "code present; advisory from code review"
reason: "35-REVIEW.md WR-03 — UX; operators often see generic Validation failed."
evidence_status: "code present; advisory from code review"
- finding: "Partial/layout draftEmpty only checks content_html (WR-04)"
category: other
reason: "35-REVIEW.md WR-04 — text-only drafts show empty preview state; server can still render text."
evidence_status: "code present; advisory from code review"
human_verification:
- test: "Open Settings → Mail → Mail templates in a running admin SPA with a plugin that registers HasMailTemplates (e.g. user plugin templates)."
expected: "All registered templates appear; customize subject/body/layout; save; Reset to file version restores file content; drift callout appears after file change."
why_human: "List/form UX, Winter-shaped flow and empty-state copy need visual confirmation beyond unit/API tests."
- test: "Edit a layout in codeeditor (HTML/text/CSS tabs); insert an image from the library; save Branding colours and logo; preview HTML/plain text; Send test to me."
expected: "CodeMirror highlighting/focus feels correct; inserted URL is absolute server URL; preview iframe is sandboxed server HTML; test mail arrives only at the signed-in admin address (Mailpit)."
why_human: "35-VALIDATION.md manual-only rows (D-09 feel, D-17 inbox rendering); visual appearance and real mail-client rendering cannot be proven by grep."
- test: "Confirm judgment-tier prohibition: postcard imports modules/lagoon/attach for AbsolutePublicURL."
expected: "Accept as intentional (D-24 / 35-01 SUMMARY threat_flag dependency-surface) or request a follow-up to move AbsolutePublicURL out of lagoon."
why_human: "PLAN prohibition said postcard must not import lagoon; implementation imports attach by design. Judgment-tier — needs explicit human resolution."
---
# Phase 35: Mail templates and layouts editor Verification Report
**Phase Goal:** Administrators edit every mail the application sends from the admin panel, as in WinterCMS's Mail templates screen. System mail and the templates plugins register through `pact.HasMailTemplates` appear in a list. Each template can get a database override of its subject and body, and the override can be reset to the file version. Layouts become admin-editable records assigned to templates, with a few predefined layouts seeded. Images can be uploaded and placed in layouts and templates. postcard renders the override when one exists, otherwise the plugin's file, so mail that already works keeps working.
**Verified:** 2026-11-13T13:43:11Z
**Status:** human_needed
**Re-verification:** No — initial verification
## Goal Achievement
Roadmap lists **Requirements: TBD** and no Success Criteria block for Phase 35. Must-haves are derived from the ROADMAP goal (Option C) and merged with PLAN frontmatter truths (D-01..D-25). `check.decision-coverage-verify`: **25/25** CONTEXT decisions honored.
### Observable Truths
| # | Truth | Status | Evidence |
| --- | --- | --- | --- |
| 1 | Administrators edit mail from Settings → Mail screens (templates, layouts, partials, branding, images) with no top-level nav | ✓ VERIFIED | `modules/cabana/mail_admin.go` + `backend_screens.go` register five Settings entries and controllers; smoke `TestMailScreensSmoke`; SPA generic FormView/ListView/SettingsFormView |
| 2 | Templates from `pact.HasMailTemplates` (and file catalog) appear as list rows after SyncIndex | ✓ VERIFIED | `postcard.SyncIndex` in `store.go`; cabana `http.go` → `mail.syncOnDatabase` → `postcard.SyncIndex`; list YAML under `backendscreens/controllers/mailtemplates/` |
| 3 | Template DB override of subject, Markdown body and layout; Reset clears override and re-mirrors file | ✓ VERIFIED | `mailer.go` per-send `NewDBSource`; `ResetOverride` in `store.go`; `go test -short ./modules/postcard -run 'TestOverride'` PASS; cabana `TestMailReset` exists |
Granular PLAN truths (35-01..04) map onto the rows above; spot-checks did not find a PLAN truth that fails while the parent row holds. Advisory WR-01..04 do not falsify these truths.
### Required Artifacts
All PLAN `must_haves.artifacts` passed `verify.artifacts` (01: 8/8, 02: 6/6, 03: 6/6, 04: 5/5).
| `brand.go` → AbsolutePublicURL | `attach/absolute.go` | logo at send | ✓ WIRED (alt path) | mechanical pattern in brand.go MISSING; call is in `store.go:330` (`attach.AbsolutePublicURL`) per 35-01 SUMMARY plan inconsistency note — same intent |
| D-01..D-25 | 35-01..04 + CONTEXT | Full decision set | ✓ SATISFIED | `check.decision-coverage-verify` 25/25 honored |
| (v1 REQ IDs) | — | none mapped to phase 35 | N/A | no orphaned Phase 35 rows in REQUIREMENTS.md |
### Anti-Patterns Found
| File | Line | Pattern | Severity | Impact |
| ---- | ---- | ------- | -------- | ------ |
| — | — | TBD/FIXME/XXX in key phase files | none found | — |
| `modules/postcard/store.go` | import | imports `lagoon/attach` | ℹ️ Info / judgment prohibition | Intentional for AbsolutePublicURL (D-24); conflicts with written prohibition text |
| 35-REVIEW WR-01..04 | — | filter/UX gaps | 📋 Advisory | Do not fail must-haves; recorded in advisory frontmatter |
| Byte-identical file mail without override | Holds — TestOverride/file path + consumer stage in gate | unverified-prohibition — human review recommended |
| goldmark not unsafe | Holds — `goldmark.New()` / Table only; no WithUnsafe | unverified-prohibition — human review recommended |
| postcard does not import cabana or lagoon | **Partial:** no cabana; **does** import `lagoon/attach` | unverified-prohibition — human resolution required (see Human Verification #3) |
| No free-text recipient on mail screens | Holds — test-send posts no recipient; server refuses recipient key | unverified-prohibition — human review recommended |
| No default role grants for mail permissions | Holds — smoke/permission tests assert zero grants | unverified-prohibition — human review recommended |
### Human Verification Required
### 1. Winter-shaped Settings → Mail flow
**Test:** Open Settings → Mail → Mail templates in a running admin SPA with a plugin that registers HasMailTemplates.
**Test:** Review prohibition vs D-24 AbsolutePublicURL placement.
**Expected:** Accept deviation or schedule follow-up extraction.
**Why human:** Judgment-tier prohibition conflict with intentional implementation.
### Gaps Summary
No must-have truths FAILED. Automated goal-backward evidence is green (12/12). Status is `human_needed` because Step 8 human items (visual UAT + judgment prohibition resolution) are non-empty — not because of implementation gaps. Advisory code-review warnings (WR-01..04) noted; they do not alone fail verification.
---
_Verified: 2026-11-13T13:43:11Z_
_Verifier: the agent (msd-verifier)_
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.