mustflow 2.107.3 → 2.108.0

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

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.payment-integrity-review
 locale: en
 canonical: true
-revision: 3
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: payment-integrity-review
-description: Apply this skill when payment, checkout, authorization, capture, refund, partial refund, subscription, invoice, trial, grace period, coupon, promotion, inventory reservation, fulfillment, entitlement, settlement, fee, chargeback, dispute, provider webhook, payment outbox, payment session, payment link, payment-provider integration, admin manual payment operation, payment logs, PCI-sensitive data handling, or payment-related tests need review for money-event integrity, idempotency, ordering, ownership, amount, currency, retry, reconciliation, ledger, or audit risk.
+description: Apply this skill when payment, checkout, authorization, capture, refund, partial refund, subscription, invoice, credit note, receipt, tax document, trial, grace period, coupon, promotion, inventory reservation, fulfillment, entitlement, settlement, fee, payout, chargeback, dispute, fraud review, card testing, provider webhook, payment outbox, payment session, payment link, payment-provider integration, admin manual payment operation, payment logs, PCI-sensitive data handling, or payment-related tests need review for money-event integrity, idempotency, ordering, ownership, amount, currency, retry, reconciliation, ledger, or audit risk.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -35,7 +35,7 @@ Review payment code as money-event integrity, not provider API success. The core
 <!-- mustflow-section: use-when -->
 ## Use When
 
-- Payment, checkout, payment-session, payment-link, authorization, capture, refund, partial refund, dispute, chargeback, settlement, fee, receipt, entitlement, fulfillment, subscription, invoice, trial, grace period, coupon, promotion, or inventory reservation logic is created, changed, reviewed, or reported.
+- Payment, checkout, payment-session, payment-link, authorization, capture, refund, partial refund, dispute, chargeback, settlement, fee, payout, receipt, invoice, credit note, tax document, entitlement, fulfillment, subscription, trial, grace period, coupon, promotion, fraud review, card testing, or inventory reservation logic is created, changed, reviewed, or reported.
 - Provider webhook handling, provider callback handling, payment outbox records, payment retry handling, timeout handling, provider reconciliation, or async payment method handling can change internal money state.
 - Client-supplied amount, currency, quantity, product, discount, shipping, tax, order, subscription, refund, or customer identifiers can influence a payment action.
 - Manual admin payment operations, payment logs, audit trails, or payment-related tests need review.
@@ -52,7 +52,7 @@ Review payment code as money-event integrity, not provider API success. The core
 <!-- mustflow-section: required-inputs -->
 ## Required Inputs
 
-- Money-event ledger: every create, authorize, capture, fulfill, refund, dispute, chargeback, settlement, adjustment, cancellation, expiration, and entitlement event that can move money or access.
+- Money-event ledger: every create, authorize, capture, fulfill, refund, partial refund, tax reversal, credit note, receipt, dispute, chargeback, settlement, payout, adjustment, cancellation, expiration, and entitlement event that can move money, evidence, or access.
 - Provider interaction ledger: payment provider calls, webhook event types, redirect handlers,
   polling, reconciliation jobs, SDK clients, idempotency keys, internal order IDs, internal payment
   IDs, attempt IDs, provider object IDs, provider reference IDs, and provider environment selection.
@@ -66,7 +66,9 @@ Review payment code as money-event integrity, not provider API success. The core
   parser or validator, database constraint when available, and the rejection path for unknown,
   stale, misspelled, or provider-shaped event types.
 - Idempotency and uniqueness ledger: logical operation IDs, provider idempotency keys, database uniqueness constraints, webhook event dedupe keys, fulfillment dedupe keys, and retry behavior.
-- Amount and currency ledger: product/cart snapshot, server-side calculation path, quantity, discounts, coupons, tax, shipping, minor-unit representation, currency, provider amount, internal ledger amount, receipt amount, and settlement amount.
+- Amount and currency ledger: product/cart snapshot, invoice and line-item snapshot, server-side calculation path, quantity, discounts, coupons, tax, shipping, minor-unit representation, currency, provider amount, internal ledger amount, receipt amount, refund amount, dispute amount, payout amount, and settlement amount.
+- Invoice, receipt, and tax ledger: invoice status, invoice line items, credit notes, receipt generation, receipt delivery, receipt lookup identifiers, tax behavior, tax jurisdiction, tax-exemption evidence, tax-rate snapshots, tax reversals, and tax-document issuance state.
+- Dispute and fraud ledger: dispute reason, evidence deadline, evidence packet inputs, refund-dispute collision policy, fraud review state, card-testing defenses, risk holds, descriptor or customer-communication evidence, and network-monitoring exposure when available.
 - Ownership ledger: user, tenant, account, order, payment session, refund, subscription, invoice, entitlement, admin actor, and provider customer ownership checks.
 - Fulfillment and entitlement ledger: when access, inventory, shipment, credits, licenses, notifications, or downstream side effects are granted or revoked.
 - Webhook and retry ledger: signature verification, raw-body handling, event storage, queue handoff, duplicate and out-of-order handling, timeout classification, backoff, and dead-letter behavior.
@@ -84,7 +86,7 @@ Review payment code as money-event integrity, not provider API success. The core
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
 
-- Tighten payment state machines, server-side amount calculation, minor-unit money handling, ownership checks, idempotency keys, provider-ID uniqueness, webhook signature verification, webhook dedupe, outbox event-type validation, queue handoff, one-time fulfillment, async payment handling, authorization/capture distinction, refund/dispute/subscription transitions, inventory and coupon reservation, timeout and retry classification, append-only ledgers, secret and card-data redaction, admin audit trails, stale payment endpoint cleanup notes, focused nightmare-path tests, and directly synchronized docs or templates.
+- Tighten payment state machines, server-side amount calculation, invoice and line-item snapshots, minor-unit money handling, tax snapshots and reversals, receipt delivery tracking, ownership checks, idempotency keys, provider-ID uniqueness, webhook signature verification, webhook dedupe, outbox event-type validation, queue handoff, one-time fulfillment, async payment handling, authorization/capture distinction, refund/dispute/subscription transitions, inventory and coupon reservation, timeout and retry classification, payout reconciliation, append-only ledgers, secret and card-data redaction, fraud and card-testing defenses, admin audit trails, stale payment endpoint cleanup notes, focused nightmare-path tests, and directly synchronized docs or templates.
 - Do not replace a focused payment-integrity fix with a broad payment platform rewrite unless the current code cannot preserve money correctness with a smaller boundary.
 - Do not add live payment secrets, real card data, real refunds, real charges, or live-provider side effects.
 
@@ -104,8 +106,11 @@ Review payment code as money-event integrity, not provider API success. The core
      strings, provider event names, stale constants, or user-controlled values become trusted outbox
      operation types.
 4. Calculate amount on the server. Treat client-supplied amount, currency, quantity, discount, coupon, tax, shipping, product ID, plan ID, or cart totals as input claims only; rebuild the payable total from trusted product, cart, account, and policy snapshots.
+   - Freeze the cart, order, invoice, subscription period, product, price, discount, shipping, tax behavior, tax rate, exchange rate, and entitlement snapshot used for the payment. Do not recalculate paid orders, refunds, chargebacks, receipts, or tax documents from current product tables.
+   - For partial refunds, calculate from line items and tax lines, not only from a manual total. Preserve refunded quantity, refunded subtotal, tax reversal, discount allocation, shipping decision, credit note link, and refund reason.
 5. Bind every payment object to its owner. Verify user, tenant, order, payment session, refund, subscription, invoice, provider customer, and admin actor ownership before read, write, refund, cancel, fulfillment, or entitlement changes.
 6. Compare every amount ledger. Trace order amount, provider request amount, provider response amount, internal money ledger, receipt, settlement, fee, refund, and entitlement amount. Flag any path where one amount can drift without reconciliation.
+   - Distinguish gross charge, captured amount, processor fee, application or platform fee, tax collected, tax liability, refund, tax reversal, dispute withdrawal, dispute fee, dispute reinstatement, payout, payout failure, reserve, and negative provider balance. Provider dashboard totals and bank deposits are not the same fact as revenue.
 7. Use integer minor units. Reject float, double, string-concatenated, rounded-late, locale-formatted, or JavaScript-number money math when it can cross currency or precision boundaries.
 8. Make payment creation idempotent. Use a stable key for one logical payment attempt, not a fresh UUID per retry. Include operation identity such as order or attempt ID, but do not include secrets or raw personal data.
 9. Use database uniqueness as the last gate. Add or verify unique constraints for provider payment IDs, provider session IDs, provider event IDs, provider refund IDs, internal ledger IDs, and fulfillment records where duplicates would move money or access twice.
@@ -115,11 +120,18 @@ Review payment code as money-event integrity, not provider API success. The core
 13. Return from webhook endpoints quickly. Persist the event, enqueue durable work, and return a provider-acceptable response without doing slow fulfillment, network fan-out, file work, or long transactions in the webhook request.
 14. Never use success redirects as proof. Treat checkout success pages, return URLs, frontend callbacks, and local storage flags as user navigation only; fulfillment must depend on verified provider state or signed server-side evidence.
 15. Run fulfillment exactly once. Guard entitlement grants, shipments, credit issuance, license creation, invoice finalization, emails with money meaning, and inventory release with unique records or state transitions.
+   - Keep internal entitlement state separate from provider subscription state. `past_due`, `unpaid`, grace period, restricted access, revocation, reactivation, and manual invoice-paid events should map through product policy rather than a direct provider-status copy.
 16. Handle asynchronous payment methods. Do not fulfill on checkout completion when the provider can still move through pending, requires_action, processing, delayed success, delayed failure, or expiry states.
 17. Separate authorization from capture. Do not treat an authorization hold as captured money. Review capture windows, partial captures, expired authorizations, cancellations, orphan authorized-but-not-captured operations, and post-authorization amount changes.
 18. Review refunds as money-out events. Check requested, pending, completed, failed, cancelled, and partial refund states; double refunds; refund failures; refund idempotency; refund ownership; refund amount/currency; ledger reversal; entitlement revocation; and receipt updates.
+   - Treat refund requests and provider refunds as separate records when provider outcomes can be pending, require customer action, fail, cancel, or arrive through provider dashboards. Use refund-request idempotency keys, not a fresh key per click and not the whole order ID when multiple partial refunds are valid.
+   - Lock or reserve refundable balance while a refund is pending when concurrent operators, jobs, or customer flows can otherwise exceed the captured amount.
 19. Handle disputes and chargebacks. Ensure dispute events affect access, account risk, support workflow, ledger entries, settlement reports, and customer-visible state without pretending the original capture still stands unchanged.
-20. Review subscriptions as state machines. Separate trialing, active, past_due, grace, unpaid, cancelled, pending cancellation, retrying, upgraded, downgraded, invoice-open, invoice-paid, and invoice-failed states.
+   - Define the refund-dispute collision policy. A pending or completed refund can collide with a dispute; avoid double compensation, preserve refund IDs and receipt evidence, and decide whether to accept, contest, or block new refunds while a dispute is open.
+   - Track evidence deadlines, reason categories, evidence packet fields, customer communications, receipt and invoice links, refund history, shipping or delivery proof, usage logs, login or download evidence, cancellation evidence, and support decisions. Winning a dispute does not erase the operational need to prevent future dispute-rate or fraud-rate exposure.
+20. Review subscriptions as state machines. Separate trialing, active, incomplete, incomplete_expired, past_due, grace, unpaid, cancelled, pending cancellation, retrying, upgraded, downgraded, invoice-open, invoice-paid, and invoice-failed states.
+   - Model dunning and entitlement policy explicitly: first-payment failure, off-session authentication required, hard decline, soft decline, retry schedule, payment-method update link, reminder sequence, grace period, restriction, revocation, reactivation, and manual invoice resolution.
+   - Review plan changes as money and entitlement events. Upgrades, downgrades, seat-count changes, proration, coupon changes, tax changes, account credits, and mid-cycle cancellations must update invoice, entitlement, credit, and refund ledgers consistently.
 21. Reserve inventory before confirming it. Check that payment, inventory, cancellation, expiration, refund, and fulfillment cannot oversell, lose stock, or keep stock reserved after an abandoned payment.
 22. Reserve coupons before consuming them. Under concurrent attempts, a coupon should not be spent twice or lost forever after a failed or expired payment. Review reservation, consumption, release, and expiry paths.
 23. Treat timeouts as unknown outcomes. A provider timeout after request submission is not a failure proof. Verify by idempotency key, provider object lookup, webhook, or reconciliation before retrying or cancelling.
@@ -127,24 +139,31 @@ Review payment code as money-event integrity, not provider API success. The core
 25. Segment the payment path. When diagnosing approval rate or decline spikes, separate frontend validation, backend request creation, provider gateway, acquirer, card network, issuer, bank, 3DS or additional authentication, and settlement evidence instead of reading one blended failure count.
 26. Keep an append-only money ledger. Prefer immutable entries for payment, capture, refund, fee, settlement, chargeback, adjustment, and correction. Flag mutable balance-only code with no event history.
 27. Reconcile provider and internal state. Check scheduled or manual reconciliation for missed webhooks, stale internal states, provider-side refunds, settlement fees, disputes, orphan authorizations, and permanently unknown operations.
+   - Reconcile payouts separately from sales. A payout is movement from provider balance to a bank account, not revenue. Check payout failure, negative provider balance, reserves, platform or connected-account liability, refunded-after-payout flows, and dispute-after-payout recovery.
+   - Reconcile provider-dashboard manual actions back into local state. Provider-side refunds, subscription cancellations, invoice voids, paid invoice overrides, dispute decisions, and tax document changes need webhook ingestion, reconciliation jobs, or explicit manual import evidence.
 28. Redact payment-sensitive data. Never log card numbers, CVV, track data, PINs, raw payment credentials, webhook secrets, bearer tokens, provider secret keys, or full provider payloads containing sensitive fields.
+   - Keep PCI scope intentionally small. Hosted checkout, tokenized payment methods, mandates, and provider components are preferable when they keep raw card data away from application servers. Never store CVC/CVV after authorization, even for recurring payments.
 29. Separate test and live payment planes. Verify API keys, webhook secrets, product IDs, price IDs, environment flags, provider account IDs, and fixtures cannot cross between test and live modes.
 30. Audit manual payment operations. Require role, reason, target object, before/after values, approver or policy evidence, operator identity, timestamp, and rollback or correction path for admin overrides.
+   - Separate admin abilities for refund, credit, invoice void, tax document reissue, dispute evidence access, subscription cancellation, entitlement override, and provider-dashboard action reconciliation. Money operations need least privilege and audit evidence, not one broad support-admin flag.
 31. Add a payment hold or kill-switch path for unsafe flows. Risky provider migrations, webhook
     regressions, reconciliation uncertainty, fraud spikes, or duplicate-money incidents need a way
     to hold fulfillment, stop captures, pause refunds, or disable a provider path without corrupting
     ledger state.
+   - Treat fraud review and card testing as payment integrity risks. High failure velocity, repeated card fingerprints, bot-like checkout attempts, high-risk score, mismatched geography, descriptor confusion, unusually fast disputes, and chargeback-rate monitoring need hold, review, rate-limit, or provider-rule evidence before fulfillment.
 32. Search for stale payment endpoints. Review old checkout paths, hidden callback URLs, deprecated provider versions, old mobile endpoints, webhook v1 handlers, and manual scripts that still mutate money state.
-33. Check public errors and support evidence. Payment failures must not lie about success, leak sensitive payment facts, or leave support with no safe correlation ID, provider object ID, or internal event ID.
-34. Test the nightmare paths. Include repeated pay-button clicks, replayed webhooks, out-of-order webhooks, success redirect plus database failure, database success plus provider timeout, amount or currency tampering, wrong order ID, concurrent double refund, pay then cancel, expired-session completion, subscription retry, provider missed webhook, orphan authorization cleanup, provider kill switch or hold state, and admin override rollback.
+33. Check invoice, receipt, and tax-document delivery. Payment success is separate from receipt generation, receipt email delivery, invoice finalization, credit note issuance, refund receipt delivery, and tax document issuance. Support should be able to find records by order ID, payment ID, invoice number, receipt number, provider object, safe customer identifier, and correlation ID.
+34. Check public errors and support evidence. Payment failures must not lie about success, leak sensitive payment facts, or leave support with no safe correlation ID, provider object ID, receipt or invoice ID, dispute ID, refund ID, or internal event ID.
+35. Test the nightmare paths. Include repeated pay-button clicks, replayed webhooks, out-of-order webhooks, success redirect plus database failure, database success plus provider timeout, amount or currency tampering, wrong order ID, concurrent double refund, pay then cancel, expired-session completion, partial refund tax reversal, refund failure, refund then dispute, dispute then refund attempt, subscription retry and dunning, provider-side manual refund, receipt delivery failure, tax-document gap, payout failure, card-testing spike, orphan authorization cleanup, provider kill switch or hold state, and admin override rollback.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - The payment surface has a money-event map, provider interaction map, identifier map,
   state-transition map, immutable event log, idempotency and uniqueness map, amount and currency map,
-  ownership map, fulfillment and entitlement map, webhook/retry map, outbox event-type validation
-  map, reconciliation and hold-state map, and audit/sensitive-data map.
+  invoice/receipt/tax map, ownership map, fulfillment and entitlement map, webhook/retry map,
+  outbox event-type validation map, reconciliation and hold-state map, dispute/fraud map, payout
+  map, and audit/sensitive-data map.
 - Any false success, duplicate money movement, duplicate fulfillment, wrong-owner action, wrong amount, wrong currency, stale event overwrite, timeout misclassification, or missing reconciliation is fixed or reported with evidence.
 - Tests or explicit verification cover the highest-risk nightmare paths available in the current scope.
 
@@ -164,7 +183,7 @@ Use configured oneshot command intents when available:
 - `test_release`
 - `mustflow_check`
 
-Prefer focused tests for duplicate operations, webhook replay, out-of-order events, ownership denial, amount tampering, timeout unknowns, and one-time fulfillment. Use broader checks when payment integrity touches shared state machines, provider adapters, database migrations, or template surfaces.
+Prefer focused tests for duplicate operations, webhook replay, out-of-order events, ownership denial, amount tampering, timeout unknowns, one-time fulfillment, partial refunds, failed refunds, refund-dispute collisions, subscription retry and dunning, receipt delivery failure, tax reversal, payout reconciliation, fraud holds, and card-testing controls. Use broader checks when payment integrity touches shared state machines, provider adapters, database migrations, or template surfaces.
 
 <!-- mustflow-section: failure-handling -->
 ## Failure Handling
@@ -173,14 +192,15 @@ Prefer focused tests for duplicate operations, webhook replay, out-of-order even
 - If a provider outcome is unknown, do not mark it failed or paid without reconciliation evidence.
 - If webhook signature verification cannot be proven because middleware hides the raw body, report that as a blocking integrity risk.
 - If duplicate prevention relies only on in-memory flags, frontend disabling, or sequential UI behavior, report the missing durable idempotency gate.
+- If invoice, receipt, tax, dispute, payout, or provider-dashboard manual-action evidence is missing, report the missing operational ledger instead of treating provider success as complete payment evidence.
 - If tests cannot hit live-provider behavior, use provider fixtures, signed webhook fixtures, fake adapters, or state-machine tests and report remaining live integration risk.
 
 <!-- mustflow-section: output-format -->
 ## Output Format
 
 - Payment surface and provider boundary reviewed
-- Money-event, provider, identifier, state, event-log, outbox event-type, idempotency, amount, ownership, fulfillment, webhook, retry, reconciliation, hold-state, audit, and sensitive-data ledgers
-- Findings or fixes for duplicate, late, out-of-order, wrong-actor, wrong-amount, wrong-currency, timeout, retry, reconciliation, and audit risks
+- Money-event, provider, identifier, state, event-log, outbox event-type, idempotency, amount, invoice, receipt, tax, ownership, fulfillment, webhook, retry, dispute, fraud, payout, reconciliation, hold-state, audit, and sensitive-data ledgers
+- Findings or fixes for duplicate, late, out-of-order, wrong-actor, wrong-amount, wrong-currency, timeout, retry, refund, subscription, tax, receipt, chargeback, fraud, payout, reconciliation, and audit risks
 - Nightmare-path tests or evidence added, run, skipped, or still missing
 - Command intents run
 - Remaining payment-integrity risk

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -18,6 +18,12 @@ route_type = "primary"
 priority = 82
 applies_to_reasons = ["code_change", "behavior_change", "data_change", "migration_change", "performance_change", "security_change", "privacy_change", "public_api_change"]
 
+[routes."small-service-platform-architecture-review"]
+category = "architecture_patterns"
+route_type = "primary"
+priority = 84
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "docs_change", "public_api_change", "data_change", "migration_change", "performance_change", "security_change", "privacy_change", "ui_change", "product_change", "package_metadata_change", "release_risk"]
+
 [routes."code-review"]
 category = "general_code"
 route_type = "primary"
@@ -60,6 +66,12 @@ route_type = "primary"
 priority = 68
 applies_to_reasons = ["docs_change", "mustflow_docs_change", "mustflow_config_change", "package_metadata_change", "security_change", "release_risk", "unknown_change"]
 
+[routes."cli-option-contract-review"]
+category = "workflow_contracts"
+route_type = "primary"
+priority = 66
+applies_to_reasons = ["public_api_change", "behavior_change", "docs_change", "test_change", "package_metadata_change", "release_risk"]
+
 [routes."cli-output-contract-review"]
 category = "workflow_contracts"
 route_type = "adjunct"
@@ -210,12 +222,24 @@ route_type = "adjunct"
 priority = 81
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "security_change", "privacy_change", "data_change", "migration_change", "docs_change", "package_metadata_change", "release_risk"]
 
+[routes."notification-delivery-integrity-review"]
+category = "general_code"
+route_type = "adjunct"
+priority = 82
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "security_change", "privacy_change", "data_change", "migration_change", "docs_change", "package_metadata_change", "release_risk"]
+
 [routes."api-misuse-resistance-review"]
 category = "general_code"
 route_type = "adjunct"
 priority = 69
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "security_change", "privacy_change", "data_change", "docs_change", "package_metadata_change"]
 
+[routes."third-party-api-integration-review"]
+category = "data_external"
+route_type = "adjunct"
+priority = 82
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "security_change", "privacy_change", "data_change", "migration_change", "docs_change", "package_metadata_change", "release_risk"]
+
 [routes."http-api-semantics-review"]
 category = "general_code"
 route_type = "adjunct"
@@ -588,6 +612,12 @@ route_type = "primary"
 priority = 65
 applies_to_reasons = ["ui_change", "product_change"]
 
+[routes."ai-product-readiness-review"]
+category = "general_code"
+route_type = "primary"
+priority = 64
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "docs_change", "public_api_change", "data_change", "performance_change", "security_change", "privacy_change", "ui_change", "product_change", "package_metadata_change", "release_risk"]
+
 [routes."prompt-contract-quality-review"]
 category = "general_code"
 route_type = "primary"
@@ -624,6 +654,12 @@ route_type = "primary"
 priority = 70
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "docs_change", "public_api_change", "data_change", "performance_change", "security_change", "privacy_change", "package_metadata_change", "release_risk"]
 
+[routes."browser-automation-reliability-review"]
+category = "general_code"
+route_type = "primary"
+priority = 73
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "docs_change", "public_api_change", "data_change", "performance_change", "security_change", "privacy_change", "ui_change", "product_change", "package_metadata_change", "release_risk"]
+
 [routes."agent-eval-integrity-review"]
 category = "general_code"
 route_type = "primary"
@@ -846,6 +882,12 @@ route_type = "adjunct"
 priority = 77
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "public_api_change", "security_change", "privacy_change", "data_change", "test_change", "docs_change", "package_metadata_change", "release_risk"]
 
+[routes."admin-control-plane-safety-review"]
+category = "security_privacy"
+route_type = "adjunct"
+priority = 79
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "public_api_change", "security_change", "privacy_change", "data_change", "test_change", "docs_change", "package_metadata_change", "release_risk"]
+
 [routes."file-upload-security-review"]
 category = "security_privacy"
 route_type = "adjunct"
@@ -960,12 +1002,24 @@ route_type = "adjunct"
 priority = 82
 applies_to_reasons = ["ui_change", "behavior_change", "code_change", "test_change", "docs_change", "web_asset_change"]
 
+[routes."frontend-component-library-review"]
+category = "ui_assets"
+route_type = "adjunct"
+priority = 84
+applies_to_reasons = ["ui_change", "behavior_change", "code_change", "test_change", "docs_change", "public_api_change", "package_metadata_change", "performance_change", "security_change", "privacy_change", "web_asset_change", "release_risk"]
+
 [routes."frontend-localization-review"]
 category = "ui_assets"
 route_type = "adjunct"
 priority = 84
 applies_to_reasons = ["ui_change", "behavior_change", "code_change", "test_change", "docs_change", "i18n_change", "web_asset_change"]
 
+[routes."website-task-friction-review"]
+category = "ui_assets"
+route_type = "adjunct"
+priority = 83
+applies_to_reasons = ["ui_change", "behavior_change", "code_change", "test_change", "docs_change", "performance_change", "security_change", "privacy_change", "public_api_change", "web_asset_change", "release_risk"]
+
 [routes."frontend-render-stability"]
 category = "ui_assets"
 route_type = "primary"