mustflow 2.107.9 → 2.108.2

package/templates/default/locales/en/.mustflow/skills/frontend-localization-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.frontend-localization-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: frontend-localization-review
-description: Apply this skill when frontend UI, product copy, messages, metadata, notifications, exports, locale handling, formatting, sorting, search, SSR hydration, RTL behavior, or i18n tests are created, changed, reviewed, or reported and localization correctness must be checked beyond visible JSX text.
+description: Apply this skill when frontend UI, product copy, messages, translation keys, message catalogs, metadata, SEO or hreflang, localized routes, notifications, exports, locale handling, fallback, translation workflow, formatting, sorting, search, SSR hydration, RTL behavior, or i18n tests are created, changed, reviewed, or reported and localization correctness must be checked beyond visible JSX text.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -29,18 +29,20 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Review frontend localization by tracing every user-visible string, locale-sensitive value, direction-sensitive layout choice, and exported text surface instead of only scanning visible JSX text.
+Review frontend localization by tracing every user-visible string, locale-sensitive value, locale route, direction-sensitive layout choice, translation workflow, and exported text surface instead of only scanning visible JSX text.
 
-The core question is: "Can the product say the right thing, in the right grammar, format, direction, tone, and channel for this user's language, region, currency, unit, and time zone?" A translated screen is not localized if placeholders, validation errors, file names, emails, metadata, numbers, dates, sort order, or fallback behavior still leak the source locale.
+The core question is: "Can the product say the right thing, in the right grammar, format, direction, tone, URL, search result, and channel for this user's language, region, currency, unit, and time zone?" A translated screen is not localized if placeholders, validation errors, file names, emails, metadata, numbers, dates, sort order, URL structure, or fallback behavior still leak the source locale.
 
 <!-- mustflow-section: use-when -->
 ## Use When
 
 - Frontend UI, product copy, forms, validation, error messages, empty states, toasts, dialogs, emails, push notifications, share text, exports, downloads, PDFs, CSVs, calendar invites, charts, canvas, SVG text, document titles, metadata, Open Graph, or SEO text are created, changed, reviewed, or reported.
-- Code adds or changes translation keys, message catalogs, `t(...)`, ICU messages, placeholders, `aria-label`, `title`, `alt`, `meta` tags, Open Graph text, browser `confirm` text, chart labels, file names, copy-to-clipboard text, or backend error-code mapping.
+- Code adds or changes translation keys, key naming, stale or missing key behavior, message catalogs, `t(...)`, ICU messages, placeholders, `aria-label`, `title`, `alt`, `meta` tags, Open Graph text, browser `confirm` text, chart labels, file names, copy-to-clipboard text, or backend error-code mapping.
 - Code adds or changes date, time, relative-time, number, currency, percent, unit, plural, list, case, collation, search normalization, truncation, string length, or user-input parsing logic.
-- UI needs to support long translated labels, pseudo localization, RTL or bidirectional text, locale-specific font fallback, language switching, server rendering, hydration, or client/server locale agreement.
-- A review or final report claims a surface is translated, localization-safe, i18n-ready, RTL-ready, locale-aware, or global-ready.
+- UI needs to support long translated labels, pseudo localization, RTL or bidirectional text, locale-specific font fallback, language switching, locale-specific routes, server rendering, hydration, or client/server locale agreement.
+- International SEO changes involve language-specific URLs, canonical links, `hreflang`, `x-default`, locale sitemaps, localized title or meta description, Open Graph, structured data, or automatic locale redirects.
+- Translation workflow, TMS sync, string freeze, glossary, translation memory, screenshot context, placeholder metadata, locale launch readiness, missing-key telemetry, or fallback monitoring is created, changed, reviewed, or reported.
+- A review or final report claims a surface is translated, localization-safe, i18n-ready, l10n-ready, RTL-ready, locale-aware, SEO-localized, or global-ready.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -48,6 +50,7 @@ The core question is: "Can the product say the right thing, in the right grammar
 - The task is only hostile layout resilience from long translated text or RTL layout without translation, formatting, or locale-state risk; use `frontend-stress-layout-review` first and this skill only for localization semantics.
 - The task is only accessibility names, labels, ARIA, keyboard, focus, or assistive-technology behavior; use `frontend-accessibility-tree-review` first and this skill only when translated names or visible-label consistency are involved.
 - The task is only copy tone in one language with no locale, formatting, fallback, or translation-key surface.
+- The task is only generic SEO unrelated to locale-specific URLs, metadata, hreflang, translated content, or locale routing.
 - No user-visible text, locale-sensitive value, user-entered text, exported text, metadata, search, sort, SSR locale, or direction-sensitive behavior is affected.
 - Verification would require an unconfigured pseudo-localization, screenshot, browser, or translation-management workflow. Report the missing localization evidence instead of inventing raw commands.
 
@@ -55,12 +58,27 @@ The core question is: "Can the product say the right thing, in the right grammar
 ## Required Inputs
 
 - User goal, changed UI or text surface, current diff or target files, framework and i18n library signals, supported locale policy, and configured command intents.
+- Locale model ledger: language, script, region, calendar, numbering system, time zone, currency,
+  measurement unit, explicit user preference, URL locale, cookie or account locale, browser hint,
+  and fallback order.
 - String exposure ledger: visible text, placeholders, labels, `aria-label`, `title`, `alt`, document title, metadata, Open Graph, toasts, validation, errors, empty states, confirm prompts, chart labels, SVG text, canvas text, clipboard text, download file names, emails, push notifications, exports, PDFs, CSV headers, and calendar invites.
-- Message-shape ledger: full sentence keys, interpolation values, grammatical context, plural categories, zero case, Korean particles or other inflection needs, tone or formality, reusable key risks, and HTML or component interpolation.
+- Translation-key ledger: key naming policy, domain or screen namespace, context, source text,
+  translator notes, key reuse, key lifecycle, stale keys, missing keys, fallback behavior, and
+  source-of-truth catalog.
+- Message-shape ledger: full sentence keys, interpolation values, placeholder names and examples, grammatical context, plural categories, select cases, zero case, Korean particles or other inflection needs, tone or formality, reusable key risks, and HTML or component interpolation.
 - Format ledger: dates, times, relative times, time zones, calendars, numbers, currency, percent, units, measurement systems, list formatting, input parsing, and display versus storage values.
 - Text-processing ledger: case conversion, search, sort, collation, accent handling, Unicode normalization, grapheme segmentation, truncation, ellipsis policy, and file or user name handling.
 - Direction and layout ledger: RTL, bidirectional user content, `dir="auto"`, logical CSS properties, direction-sensitive icons, font fallback, line height, long translated labels, pseudo localization, and locale-specific screenshot coverage.
 - Runtime locale ledger: language versus region versus currency versus time zone versus unit settings, fallback behavior, missing-key handling, server-rendered locale, client hydration locale, and backend error-code mapping.
+- SEO and routing ledger: localized URL shape, route locale priority, automatic redirects, canonical
+  links, `hreflang`, `x-default`, locale sitemap, translated metadata, Open Graph, structured data,
+  and crawler-visible content.
+- Translation workflow ledger: key extraction, static validation, TMS or XLIFF sync, glossary,
+  translation memory, screenshot context, string freeze, human review requirements, AI translation
+  limits, locale launch threshold, and release blocking rules.
+- Operations ledger: missing-key rate, fallback rate, bundle load failures, per-locale error rate,
+  conversion or task metrics, locale-specific support tickets, and safe logging fields such as
+  requested locale, resolved locale, fallback chain, time zone, and currency.
 - Evidence level: static string inventory, catalog diff, pseudo-localization evidence, locale snapshot evidence, configured tests, SSR hydration evidence, or missing evidence.
 
 <!-- mustflow-section: preconditions -->
@@ -69,6 +87,8 @@ The core question is: "Can the product say the right thing, in the right grammar
 - The task matches the Use When conditions and does not match the Do Not Use When exclusions.
 - Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
 - Existing local patterns for message catalogs, ICU syntax, locale routing, formatters, error-code mapping, pseudo localization, RTL support, and exported text have been searched before adding a new pattern.
+- Locale decisions are treated as product state, not only presentation. Do not assume language,
+  country, currency, time zone, and measurement unit are the same setting.
 - If localization changes affect layout, accessibility, payment, business rules, security, or API contracts, also apply the narrower matching skill for that boundary.
 
 <!-- mustflow-section: allowed-edits -->
@@ -79,7 +99,9 @@ The core question is: "Can the product say the right thing, in the right grammar
 - Add or correct plural, zero, context-specific, tone-specific, Korean particle, or inflection-safe messages when the project pattern supports them.
 - Replace ad hoc date, time, number, currency, unit, list, sort, search, and segmentation logic with locale-aware helpers or existing project formatters.
 - Add or refine RTL, `dir="auto"`, logical CSS property, pseudo-localization, locale screenshot, missing-key, backend error-code mapping, and export-text coverage where existing project patterns support them.
-- Do not invent a translation-management system, rewrite all catalogs, install i18n packages, machine-translate production copy, or broaden product language policy beyond the changed surface.
+- Add or refine localized route metadata, `hreflang`, canonical, locale sitemap, fallback telemetry,
+  or key lifecycle checks where existing project patterns support them.
+- Do not invent a translation-management system, rewrite all catalogs, install i18n packages, machine-translate production copy, change legal or pricing copy semantics, or broaden product language policy beyond the changed surface.
 
 <!-- mustflow-section: procedure -->
 ## Procedure
@@ -93,74 +115,144 @@ The core question is: "Can the product say the right thing, in the right grammar
 3. Check context-specific wording.
    - Do not reuse a generic key when the same source word means different things, such as file open, business open, and public status.
    - Prefer keys that name the product context, user action, and destination surface rather than a short dictionary word.
-4. Check destructive and action labels as complete phrases.
+4. Check translation-key lifecycle.
+   - Do not use raw source prose as a stable key when ordinary copy editing would invalidate all
+     translations.
+   - Do not use dictionary keys such as `ok`, `title`, `description`, or `submit` when the key
+     lacks product context.
+   - Check added, renamed, unused, orphaned, and missing keys, including keys that exist only in
+     default-language catalogs or only in the translation platform.
+   - Missing keys and fallback usage should be visible in development, CI, staging, or production
+     diagnostics according to project policy.
+5. Check destructive and action labels as complete phrases.
    - Do not build labels like `Delete {item}` from separate translated parts when languages need different order, case, or particles.
    - Use context-specific messages such as delete project, delete file, or delete account.
-5. Check plural and zero cases.
+6. Check plural, select, and zero cases.
    - Do not model plural as only `count === 1`.
-   - Use ICU plural or the project's plural system for all supported locale categories.
+   - Use ICU plural, select, or the project's message system for all supported locale categories and
+     state or gender variants.
    - Give zero-result states their own UX wording when "0 items" would be awkward or misleading.
-6. Check language-specific grammar traps.
+   - Keep complex plural or select branches as complete sentences so translators can move words,
+     variables, and clauses safely.
+7. Check language-specific grammar traps.
    - For Korean, review particles such as eun/neun, i/ga, eul/reul, and wa/gwa or avoid the particle with a safer sentence shape.
    - For other languages, check case, gender, noun class, politeness, or inflection needs when dynamic values are inserted into prose.
-7. Check tone and formality inside one flow.
+   - Prefer neutral rewrites over collecting sensitive profile attributes such as gender only to
+     satisfy grammar in one message.
+8. Check placeholder and rich-context metadata.
+   - Named placeholders should explain whether the value is a person, organization, URL, amount,
+     count, product name, untranslated brand term, or user-provided text.
+   - Translators need screenshots, character limits, tone, glossary terms, and examples for
+     ambiguous words such as free, open, archive, owner, and plan.
+9. Check tone and formality inside one flow.
    - Compare adjacent labels, confirmations, validation messages, empty states, and recovery actions.
    - A flow that mixes formal and casual voice should be fixed or reported as product-language drift.
-8. Check date, time, and relative-time formatting.
+10. Check date, time, calendar, and relative-time formatting.
    - Reject manual assembly such as `year + '.' + month + '.' + day`.
    - Use locale-aware formatters and confirm whether the user's time zone, server time zone, and stored instant can shift deadlines, bookings, billing dates, or "yesterday" labels.
+   - Store instants and local event time-zone identifiers intentionally. Recurring local-time events
+     should not become naive UTC repeats when daylight-saving or civil-time rules matter.
    - Treat `new Date()` in render paths, server-rendered relative time, and client hydration time as mismatch risks.
-9. Check numbers, currency, percent, and units.
+11. Check numbers, currency, percent, and units.
    - Do not rely on comma insertion, fixed decimal assumptions, or locale-agnostic `Number(input)` parsing.
    - Separate display format from canonical stored value.
    - Keep language, region, currency, time zone, and measurement unit as separate settings unless the product has an explicit rule tying them together.
-10. Check collation, search, and normalization.
+   - For prices, invoices, receipts, taxes, and billing text, distinguish display currency,
+     settlement or charge currency, tax inclusion, rounding, exchange-rate snapshot, and legal
+     document requirements.
+12. Check collation, search, and normalization.
    - Do not trust default `sort()`, raw `localeCompare` without locale intent, or plain `toLowerCase()` for user-facing search and sort.
    - Use locale-aware collation where order matters.
    - Normalize Unicode when comparing user names, filenames, tags, search queries, accents, combining characters, or Hangul variants.
-11. Check grapheme-safe length, truncation, and ellipsis.
+   - Align client filtering, database collation, and search-engine analyzers so search results do
+     not differ by layer.
+13. Check names, addresses, phone numbers, and user data.
+   - Do not force global users into first-name/last-name, state/ZIP-only addresses, numeric phone
+     numbers, numeric postal codes, ASCII-only names, or fixed short field limits.
+   - Treat names, phone numbers, postal codes, and identifiers as display strings unless the domain
+     has a validated canonical structure.
+14. Check grapheme-safe length, truncation, and ellipsis.
    - Do not use `.length` and `slice(0, n)` when user-visible text may contain emoji, flags, skin tones, combining marks, or complex scripts.
    - Use grapheme-aware segmentation or existing utilities.
    - Choose ellipsis by content meaning: paths may need middle truncation, names may need enough disambiguating text, and amounts should not be truncated.
-12. Check RTL and bidirectional text.
+15. Check RTL and bidirectional text.
    - Replace physical `left` and `right` assumptions with logical `start`, `end`, `inline-start`, and `inline-end` where direction depends on language.
    - Use `dir="auto"` for user-generated names, comments, reviews, addresses, chat, and profile text when direction may differ from the UI locale.
+   - Ensure document or route shells set compatible `lang` and `dir` values, not only leaf text.
    - Do not mirror all icons blindly. Back, next, drawer, and carousel direction may flip; play, download, clock, and brand icons usually should not.
-13. Check translated layout resilience.
+16. Check translated layout resilience.
    - Long German, French, Vietnamese, Arabic, pseudo-localized, and compact CJK labels need real fixtures.
    - Fixed-width buttons, tabs, table headers, modal titles, `white-space: nowrap`, and fixed-height rows should be routed to `frontend-stress-layout-review` when geometry changes are needed.
-14. Check font fallback.
+17. Check font fallback.
    - CJK, Thai, Arabic, Hindi, and emoji may need safe fallback fonts, line-height tolerance, and real glyph coverage.
    - Watch icon fonts, fake bold, missing weights, and square tofu glyphs.
-15. Check pseudo localization and locale snapshots.
+18. Check pseudo localization and locale snapshots.
    - Prefer pseudo localization for hardcoded strings, missing keys, broken interpolation, glyph support, and expansion stress before real translations arrive.
    - For high-trust flows, compare at least a long-language locale, an RTL locale, and a dense CJK or Japanese-style locale when the project has such coverage.
-16. Check SSR and hydration locale agreement.
+19. Check locale routing and preference priority.
+   - Prefer explicit user or URL locale over `Accept-Language` or browser hints. Browser hints
+     should not overwrite a user's saved or URL-selected language.
+   - Define priority across URL locale, account preference, cookie, browser hint, and default
+     locale so server and client choose the same locale.
+   - Avoid one URL serving many languages unless cache, SEO, and `Vary` behavior are explicitly
+     designed.
+20. Check SSR and hydration locale agreement.
    - Server and client must receive compatible locale, time zone, messages, and formatter inputs.
    - Default-language server output followed by client language switching can cause flicker, hydration mismatch, SEO drift, and different date or number text on first render.
-17. Check fallback and missing-key behavior.
+21. Check fallback and missing-key behavior.
    - In development, missing keys should be loud enough to catch.
    - In production, fallback should protect the user while logs, metrics, or diagnostics make the missing translation visible to maintainers.
    - Do not treat silent English fallback as a successful localization state.
-18. Check HTML and rich text in translations.
+   - Separate locale fallback, namespace fallback, key fallback, runtime bundle-load fallback, and
+     SEO fallback. They solve different failures and need different evidence.
+22. Check international SEO.
+   - Locale variants should have crawler-visible, stable URLs when SEO matters.
+   - Check `lang`, localized title and meta description, Open Graph, canonical URL,
+     self-referencing and reciprocal `hreflang`, `x-default`, locale sitemap, and structured data
+     when those surfaces exist.
+   - Do not canonical every translated page to the source-language URL unless the product intends
+     those localized pages not to be indexed.
+   - Avoid forced automatic redirects that prevent users or crawlers from reaching other locale
+     versions.
+23. Check HTML and rich text in translations.
    - Do not let translators edit raw HTML when component interpolation can preserve link, emphasis, and accessibility structure safely.
    - Links and emphasis inside a sentence must be movable by locale without exposing XSS, broken tags, or fixed English word order.
-19. Check backend error message boundaries.
+24. Check backend error message boundaries.
    - Do not show raw backend prose such as "Invalid password" directly in localized UI.
    - Prefer stable error codes mapped to localized frontend messages, with safe fallback for unknown codes.
-20. Check export, share, and notification surfaces.
+25. Check image, media, and culturally loaded assets.
+   - Text embedded in images, screenshots, app-store assets, email headers, PDFs, videos, and
+     onboarding media bypasses normal translation pipelines unless assets are locale-keyed.
+   - Review flags-as-language selectors, culturally loaded symbols, gestures, holidays, maps,
+     colors, and people imagery when the surface is public or high-trust.
+26. Check export, share, and notification surfaces.
    - Confirm CSV headers, PDF receipts, downloaded file names, email subjects, email bodies, push notifications, share text, clipboard output, printed output, and calendar invites follow the same language and formatting policy as the screen.
-21. Report evidence by surface.
+27. Check translation workflow and release gates.
+   - Key extraction, catalog validation, placeholder parity, ICU syntax, unused-key cleanup,
+     missing-key blocking, TMS or XLIFF sync, glossary, translation memory, screenshot context,
+     string freeze, human review, and locale launch thresholds should be named when the task claims
+     production localization readiness.
+   - AI or machine translation may be a draft input, but legal, billing, privacy, security,
+     medical, tax, refund, and marketing claims need the review path required by the product.
+28. Check operations and telemetry.
+   - Per-locale missing-key rate, fallback rate, bundle load failure, error rate, conversion,
+     support tickets, search traffic, refund or billing contacts, and localized-route crawl health
+     should be observable for launched locales when the project has such telemetry.
+   - Logs may include requested locale, resolved locale, fallback chain, time zone, currency, and
+     route locale, but should not become user fingerprinting or leak sensitive content.
+29. Report evidence by surface.
    - Separate string-inventory evidence, catalog evidence, formatter evidence, pseudo-localization evidence, screenshot evidence, SSR evidence, and export or notification evidence.
-   - If a claim is static-only, say which runtime locale, time zone, RTL, pseudo-localization, or export proof is missing.
+   - If a claim is static-only, say which runtime locale, time zone, RTL, pseudo-localization, SEO,
+     translation workflow, or export proof is missing.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - User-visible strings across screen, metadata, notifications, exports, downloads, and assistive labels are either localized, intentionally excluded, or reported.
-- Messages use full translation units, named interpolation, contextual keys, plural and zero handling, tone consistency, and grammar-safe dynamic values where relevant.
-- Dates, times, numbers, currencies, units, search, sort, case conversion, Unicode normalization, grapheme length, truncation, RTL, bidi text, font fallback, SSR locale, fallback, backend errors, and rich text are fixed, ruled out, or reported where relevant.
-- Localization readiness claims distinguish static catalog evidence from pseudo-localization, locale snapshot, SSR, runtime formatter, and export evidence.
+- Messages use full translation units, named interpolation, contextual keys, plural, select, zero handling, tone consistency, and grammar-safe dynamic values where relevant.
+- Translation keys, locale routes, fallback behavior, SEO metadata, `hreflang`, canonical behavior, translation workflow, and missing-key telemetry are fixed, ruled out, or reported where relevant.
+- Dates, times, numbers, currencies, units, names, addresses, search, sort, case conversion, Unicode normalization, grapheme length, truncation, RTL, bidi text, font fallback, SSR locale, fallback, backend errors, and rich text are fixed, ruled out, or reported where relevant.
+- Localization readiness claims distinguish static catalog evidence from pseudo-localization, locale snapshot, SSR, runtime formatter, SEO, translation workflow, operations telemetry, and export evidence.
 
 <!-- mustflow-section: verification -->
 ## Verification
@@ -183,9 +275,9 @@ Use the narrowest configured unit, component, i18n, screenshot, build, docs, rel
 ## Failure Handling
 
 - If a string surface cannot be enumerated, report the missing exposure ledger before claiming localization coverage.
-- If the project has no plural, formatter, collation, segmentation, pseudo-localization, or missing-key pattern, preserve existing behavior and report the missing project contract instead of inventing a broad framework.
+- If the project has no plural, formatter, collation, segmentation, localized-route, SEO, pseudo-localization, translation-workflow, or missing-key pattern, preserve existing behavior and report the missing project contract instead of inventing a broad framework.
 - If language, region, currency, time zone, or unit settings are conflated, avoid patching one locale branch only; report the model issue or make the smallest local split required by the changed surface.
-- If translation changes alter accessibility names, focus recovery, layout geometry, payment meaning, legal copy, or security-sensitive messaging, apply the matching skill before continuing that part.
+- If translation changes alter accessibility names, focus recovery, layout geometry, payment meaning, legal copy, SEO indexing, privacy disclosures, or security-sensitive messaging, apply the matching skill before continuing that part.
 - If a configured test or build fails after a localization change, preserve the failing intent and output tail, then use `failure-triage` before broadening the fix.
 - If verification requires unconfigured browser, pseudo-localization, screenshot, SSR, export, or translation-management tooling, stop at that boundary and report the skipped check.
 
@@ -194,9 +286,9 @@ Use the narrowest configured unit, component, i18n, screenshot, build, docs, rel
 
 - Frontend localization surface reviewed
 - String exposure ledger
-- Message-shape, plural, zero, grammar, tone, formatter, search, sort, normalization, segmentation, RTL, bidi, font, SSR, fallback, backend-error, rich-text, export, share, and notification checks where relevant
+- Locale model, translation-key, message-shape, plural, select, zero, grammar, tone, formatter, search, sort, normalization, segmentation, RTL, bidi, font, locale routing, SEO, SSR, fallback, backend-error, rich-text, workflow, operations, export, share, and notification checks where relevant
 - Localization fixes or recommendations
-- Evidence level: static inventory, catalog, configured test, pseudo-localization, screenshot, SSR, export, manual-only, missing, or not applicable
+- Evidence level: static inventory, catalog, configured test, pseudo-localization, screenshot, SEO, SSR, translation workflow, operations telemetry, export, manual-only, missing, or not applicable
 - Command intents run
 - Skipped localization checks and reasons
 - Remaining localization risk

package/templates/default/locales/en/.mustflow/skills/notification-delivery-integrity-review/SKILL.md

@@ -0,0 +1,226 @@
+---
+mustflow_doc: skill.notification-delivery-integrity-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: notification-delivery-integrity-review
+description: Apply this skill when code is created, changed, reviewed, or reported and notification systems, email, push, in-app notifications, SMS, notification preferences, unsubscribe, suppression, digest, quiet hours, timezone scheduling, rate limits, deduplication, retries, provider webhooks, delivery attempts, templates, notification inboxes, notification audit logs, or notification provider integrations need review for delivery integrity, user consent, duplicate prevention, channel policy, and explainability.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.notification-delivery-integrity-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Notification Delivery Integrity Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review notification systems as event, policy, schedule, delivery, provider, suppression, inbox, and audit flows rather than as a single send call.
+
+The review question is not "did the code send a notification?" It is "can the system explain which source event created which notification intent, why each recipient and channel was allowed or suppressed, when delivery was attempted, what the provider accepted or rejected, and how retries, duplicates, preferences, timezone, digest, and user safety were handled?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code creates, changes, reviews, or reports notification generation, recipient selection, email, push, SMS, in-app notification, digest, reminder, campaign, announcement, marketing message, transactional message, security alert, receipt, legal notice, or product activity alert behavior.
+- Code touches notification preferences, unsubscribe links, preference centers, one-click unsubscribe headers, suppression lists, bounce handling, spam complaints, invalid push tokens, quiet hours, timezone scheduling, rate limits, duplicate prevention, aggregation windows, retry policy, queue workers, provider adapters, provider webhooks, or delivery audit logs.
+- Code adds or changes notification templates, localization, subject lines, push payloads, in-app cards, deep links, sensitive preview text, provider message IDs, message tags, campaign IDs, or operator tools that answer why a notification was sent or suppressed.
+- A review or final report claims notification delivery is idempotent, retry-safe, unsubscribe-safe, digest-safe, timezone-safe, zero-downtime, provider-ready, inbox-ready, privacy-safe, or explainable to support and operators.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only a generic external provider boundary with no notification lifecycle, preference, or user-message semantics; use `adapter-boundary`.
+- The task is only generic rate-limit mechanics, retry policy, queue settlement, or idempotency outside notifications; use the narrower integrity skill first.
+- The task is only visible frontend copy, translation keys, date or number formatting, RTL, SEO, or export localization; use `frontend-localization-review` first and this skill only for notification channel semantics.
+- The task is primarily payment, credit, authentication, security, file, or deployment integrity; use the narrower domain skill first and this skill for notification-specific delivery and preference behavior.
+- The operation is local-only logging, analytics, or telemetry that no user receives and no operator treats as a notification.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Notification event ledger: source event, producer, causation ID, event schema version, outbox record, replay or backfill source, and whether the event is a fact, request, or best-effort signal.
+- Notification intent ledger: notification type, recipient, tenant or scope, category, priority, semantic dedupe key, template or semantic version, policy snapshot, and intended user-visible outcome.
+- Recipient, channel, and category ledger: security, transactional, receipt, legal, product activity, social, marketing, recommendation, reminder, or digest classification; channel eligibility; fallback policy; and mandatory versus optional delivery rules.
+- Preference and legal policy ledger: user, email address, device, tenant, workspace, channel, category, scope, consent source, unsubscribe state, legal override, and final pre-send preference recheck.
+- Suppression ledger: hard bounce, soft bounce, complaint, unsubscribe, invalid push token, inactive device, deleted account, privacy deletion, operator block, provider suppression, and whether suppression overrides user preferences.
+- Schedule, timezone, quiet hours, and digest ledger: user, device, workspace, or tenant timezone; recurring local intent; next UTC run; daylight-saving behavior; quiet hours; aggregation window; digest window; digest ID; and delayed or canceled delivery rules.
+- Delivery job and attempt ledger: queue, priority, channel, provider, provider account or domain, idempotency key, next attempt time, attempt count, retry class, request hash, provider message ID, outcome, latency, and dead-letter state.
+- Provider event ledger: provider webhook signature, provider event ID, message ID, bounce, complaint, delivered or accepted event, open or click event, token invalidation, duplicate event, out-of-order event, and reconciliation path.
+- In-app inbox ledger: inbox item snapshot, read or unread state, archive, delete, expiry, unread count, pagination, mark-all-read boundary, resource deletion fallback, and permission-lost behavior.
+- Audit, security, privacy, and operations ledger: why sent, why suppressed, who or what triggered it, sensitive body retention, redaction, account deletion behavior, operator resend rules, dry run, sample, canary, ramp-up, kill switch, campaign cancel, and cost or volume estimate.
+- Relevant command-intent contract entries for tests, builds, docs, release metadata, and mustflow validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- Existing local notification, outbox, queue, idempotency, preference, provider adapter, template, localization, audit, and operator patterns have been searched before adding new shapes.
+- Missing source event, preference, suppression, provider webhook, or audit evidence can be reported without guessing.
+- If repeated attempts move money, permissions, personal data, security alerts, legal notices, or durable business state, also apply the matching payment, security, idempotency, queue, retry, rate-limit, transaction, or localization skill.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten notification event, notification intent, schedule, delivery job, delivery attempt, provider event, suppression, preference snapshot, in-app inbox, audit, and operator evidence records.
+- Split one `sendNotification`-style path into source event, intent, schedule, delivery attempt, provider event, inbox, and audit boundaries when local architecture supports it.
+- Add or tighten semantic dedupe keys, unique constraints, aggregation windows, digest state, pre-send preference rechecks, bounce and complaint suppression, provider webhook verification, retry classification, DLQ handling, quiet-hour handling, timezone-safe scheduling, and focused tests.
+- Add or tighten template snapshot, sensitive-content redaction, lockscreen-safe push payload, deep-link permission recheck, account deletion cancellation, and support-facing why sent or why suppressed evidence.
+- Do not add live provider calls, mass sends, campaigns, local servers, worker daemons, browser sessions, provider dashboard changes, load tests, or raw production replay outside the configured command contract.
+- Do not treat provider API success, push acceptance, email open, frontend disabling, in-memory dedupe, or a log line as proof of actual user delivery or delivery integrity.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Split the lifecycle before judging correctness.
+   - Name the source event, notification intent, schedule or delivery plan, delivery attempt, provider event, suppression decision, in-app inbox item, and audit record.
+   - A source event such as comment created, payment failed, password changed, or terms updated should not directly become an email API call unless the system intentionally accepts the missing replay and audit boundary.
+   - If source event, notification intent, schedule, delivery attempt, and provider event are collapsed into one row or function, report which duplicate, retry, suppression, or explainability risk that hides.
+2. Classify the notification type.
+   - Security alerts, transactional messages, receipts, legal notices, product activity, social updates, marketing, recommendations, reminders, and digests have different consent, urgency, content, and retry rules.
+   - Do not use one global opt-out to decide every category.
+   - Do not use a product notification label to bypass marketing consent.
+3. Keep source events durable.
+   - Prefer an outbox or equivalent durable record when a business transaction should produce notifications after commit.
+   - Backfill and replay should be able to regenerate missing intents while excluding already-sent or intentionally suppressed notifications.
+   - Record causation and event schema version so later operators can explain why the intent exists.
+4. Review recipient and scope selection.
+   - Bind recipients to tenant, workspace, organization, team, project, resource, role, and permission at intent creation time.
+   - Recheck permission before send and again on click when the target resource may have been deleted, hidden, or permission-revoked.
+   - B2B notifications should not let one tenant's preference or suppression silence another tenant's legally or operationally distinct message.
+5. Review preference and legal policy as data.
+   - Store preference decisions by user, address or device, channel, category, and scope where the product needs those dimensions.
+   - Snapshot the policy used for an intent, then re-evaluate the latest preference, permission, and suppression before delivery.
+   - Record "why suppressed" with enough detail for support without logging sensitive content.
+6. Review email as provider acceptance, not inbox truth.
+   - API success usually means the provider accepted the request, not that the message reached an inbox.
+   - Check sender domain separation, SPF, DKIM, DMARC, reverse DNS, TLS, From alignment, Message-ID, tracking-domain reputation, and provider account or IP pool boundaries where the repository owns them.
+   - Separate transactional or relationship mail from commercial or marketing mail.
+   - Implement one-click unsubscribe where the channel and jurisdiction require it, and keep preference-page GET links from mutating state under link scanners.
+   - Treat hard bounce and complaint as suppression events. Soft bounces need counted policy, not infinite retry. Suppression should override a user's "send me mail" preference when the address is not deliverable or has complained.
+7. Review push as a wake-up signal, not guaranteed display.
+   - FCM, APNs, or another push provider accepting a message does not prove the user saw it.
+   - Store push token records per device, app installation, account, tenant, platform, permission status, locale, timezone, app version, last seen, last success, and invalidated time where those dimensions matter.
+   - Logout and account switching must detach or fence old push tokens so one account's private notification cannot appear on another account's device.
+   - Use a collapse key only for replaceable messages. Do not collapse chat, security, payment, or audit-significant events that users must receive individually.
+   - Keep lockscreen push text safe for the most sensitive supported tenant and account setting.
+8. Review the in-app inbox as a product record.
+   - In-app inbox entries need stable snapshots, read or unread state, archive, delete, expiry, pagination, unread count, and multi-device sync semantics.
+   - Use a mark_all_read_before boundary or equivalent when mark-all-read races with newly created notifications.
+   - Decide whether opening a push, visiting the target resource, explicit read, or mark-all-read changes inbox state.
+   - Handle deleted resources and permission-lost targets with safe fallback text instead of leaking or dead-ending.
+9. Separate dedupe from aggregation.
+   - Exactly-once delivery is not a realistic assumption. Make duplicate handling durable and observable.
+   - Use a semantic dedupe key such as source event, notification type, recipient, scope, channel, and template or semantic version.
+   - Keep notification intent dedupe separate from delivery-attempt dedupe. One intent may create email, push, and in-app channel attempts.
+   - Aggregation windows intentionally merge related events; dedupe prevents the same event from being applied twice. Do not hide aggregation as "already sent."
+10. Review digest as a separate product.
+   - Define the digest window, timezone, quiet hours, priority, maximum items, ordering, inclusion rule, retry policy, failure policy, and whether entries are event bundles or current-state snapshots.
+   - Persist digest_id, digested_at, included item identities, and excluded item reasons.
+   - Decide whether failed digest delivery returns items to a later digest, retries the same digest, or marks them intentionally missed.
+11. Review scheduling and civil time.
+   - Identify whether profile timezone, device timezone, browser timezone, workspace timezone, billing timezone, or tenant timezone owns the schedule.
+   - Store recurring local intent plus next UTC run when a user asks for local-time delivery.
+   - Handle daylight-saving transitions, nonexistent local times, duplicated local times, missing timezone, user travel, and workspace changes.
+   - Scheduled workers need claim, lease, visibility, and reaper behavior so multiple workers do not send the same due notification.
+12. Review rate limits by purpose.
+   - Separate user-experience limits, system overload limits, provider limits, tenant fairness limits, channel limits, category limits, and sender-domain or provider-account limits.
+   - A marketing campaign should not starve password resets, receipts, or security alerts.
+   - Burn enqueue quota before creating expensive fanout work when the producer can overload queues or providers.
+13. Review retries and queues by outcome uncertainty.
+   - Use exponential backoff with jitter and bounded attempts.
+   - Classify retryable failures, permanent failures, and unknown provider outcome separately.
+   - Do not retry malformed templates, unsubscribed recipients, hard-bounced addresses, invalid push tokens, permission-denied targets, or deleted accounts as transient failures.
+   - Separate critical, transactional, normal, bulk, and digest queues or concurrency budgets where one class can starve another.
+   - Poison messages need DLQ reason, safe payload summary, replay eligibility, and ownership.
+14. Review provider webhooks as untrusted and replayable.
+   - Verify provider webhook signatures before accepting bounce, complaint, delivery, open, click, token invalidation, or provider status events.
+   - Store provider event IDs or normalized message ID plus event type to make handlers idempotent.
+   - Tolerate duplicate and out-of-order webhook events. Provider delivered, bounced, complaint, open, and click events may not arrive in useful order.
+   - Keep provider receipt separate from follow-up actions such as suppression, token invalidation, inbox update, or campaign metrics.
+15. Review templates and rendering time.
+   - Decide whether subject, body, push text, in-app card, deep link, and fallback text are snapshotted at intent creation or rendered at delivery.
+   - Snapshot legal, receipt, payment, and security content that must reflect the facts at send time.
+   - Re-render product activity content only when deleted resources, missing permissions, localization, and fallback states are safe.
+   - Escape variables for each channel separately: HTML email, plaintext email, push payload, in-app UI, URL, log, and provider metadata are different output domains.
+16. Review security, privacy, and deletion.
+   - Do not put sensitive customer, payment, document, health, legal, or security details in lockscreen push text, email subject lines, logs, provider tags, analytics, or provider metadata unless the product policy explicitly allows it.
+   - Account deletion, tenant deletion, and privacy erasure should cancel pending deliveries and mask retained notification bodies while preserving legally required records separately.
+   - Unsubscribe tokens should be scoped, opaque or HMAC-protected, non-enumerable, and unable to expose account settings beyond the intended preference action.
+17. Review channel fallback deliberately.
+   - In-app can be the durable product record, push can be immediacy, email can be long-form asynchronous delivery, digest can be low-frequency summary, and SMS can be high-cost exceptional delivery.
+   - Do not automatically email because push timed out unless the notification category explicitly allows that user experience and duplicate risk.
+   - Record fallback decisions so support can distinguish "not sent by policy" from "sent on another channel."
+18. Review fanout, campaigns, and operations.
+   - Large announcements need target-count preview, dry run, sample, canary, ramp-up, rate control, campaign cancel, kill switch, expected cost, suppression count, and actual send count.
+   - Queue jobs should check campaign cancel or kill-switch state immediately before send.
+   - Tenant quotas should prevent one customer's automation or campaign from delaying other tenants' critical messages.
+19. Review observability and operator tools.
+   - Operators need to answer why sent, why suppressed, when scheduled, which attempt ran, which provider response arrived, what webhook updated state, and what preference or suppression state applied.
+   - Logs and metrics should use bounded labels and safe IDs, not full message bodies, email bodies, private resource names, raw prompts, or direct personal data.
+   - Re-send tools must define whether they reuse the old intent, create a new intent, respect current preferences, or preserve the original policy snapshot.
+20. Test the hostile paths.
+   - Cover duplicate source events, concurrent intents, provider timeout after request send, retry after unknown provider outcome, hard bounce, complaint, invalid push token, unsubscribe, link scanner, quiet hours, DST, missing timezone, digest failure, mark_all_read_before race, deleted resource, permission loss, account deletion, provider webhook duplicate, provider webhook out of order, DLQ replay, campaign cancel, and backfill exclusion of already-sent notifications.
+   - If deterministic provider, timezone, push, email, webhook, queue, or browser evidence is not configured, report static risk and missing manual or integration proof instead of claiming production delivery safety.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Source event, notification intent, schedule, delivery attempt, provider event, suppression, preference, in-app inbox, and audit boundaries are explicit or the missing boundary is reported.
+- Channel classification, consent, unsubscribe, suppression, legal override, final pre-send recheck, and fallback behavior are explicit.
+- Email, push, in-app, digest, timezone, quiet hours, rate-limit, retry, queue, provider webhook, template, security, privacy, deletion, campaign, and operator-tool risks are fixed or reported.
+- Notification-delivery claims distinguish provider acceptance, delivery attempt, user-visible inbox record, provider webhook event, open or click telemetry, and actual user action.
+- Tests or evidence cover duplicate, retry, suppression, digest, timezone, webhook, permission, deletion, and operations paths according to scope.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured test, build, docs, release, or mustflow intent that covers changed notification behavior and synchronized template surfaces. Do not infer raw email sends, push sends, live provider calls, provider dashboard actions, local servers, queue workers, webhook tunnels, load tests, browser sessions, or campaign dry runs outside the command contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the source event or notification intent cannot be named, report that the notification path is not reviewable for delivery integrity yet.
+- If duplicate prevention depends only on frontend disabling, memory, provider acceptance, or a log line, report the missing durable gate.
+- If preference, suppression, legal override, or permission evidence is missing, fail closed for optional notifications and report mandatory-notification policy gaps.
+- If a configured command fails, preserve the failing intent, failing assertion or output tail, and the notification invariant it exercised before editing again.
+- If safe repair requires schema migration, provider configuration, DNS or sender-domain setup, live deliverability testing, push entitlement setup, legal review, production traffic replay, or operator dashboard work outside the current scope, complete local verification and report the missing boundary.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Notification delivery boundary reviewed
+- Source event, notification intent, recipient/channel/category, preference/legal policy, suppression, schedule/timezone/quiet-hours/digest, delivery job and attempt, provider event, in-app inbox, audit, security, privacy, fanout, and operations ledgers checked
+- Email, push, in-app, digest, dedupe, rate-limit, retry, queue, provider webhook, template, deletion, and fallback findings
+- Notification-delivery fixes made or recommended
+- Evidence level: configured-test evidence, schema evidence, provider or framework evidence, static review risk, manual-only, missing, or not applicable
+- Command intents run
+- Skipped notification diagnostics and reasons
+- Remaining notification-delivery risk