mustflow 2.107.9 → 2.108.2

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"
@@ -216,6 +222,12 @@ 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"
@@ -600,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"
@@ -636,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"
@@ -858,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"
@@ -972,6 +1002,12 @@ 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"

package/templates/default/locales/en/.mustflow/skills/small-service-platform-architecture-review/SKILL.md

@@ -0,0 +1,273 @@
+---
+mustflow_doc: skill.small-service-platform-architecture-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: small-service-platform-architecture-review
+description: Apply this skill when a multi-product platform, app factory, solo-developer portfolio platform, many-small-services architecture, shared account portal, Product Registry, shared auth, billing, credits, entitlements, admin console, deployment factory, analytics, logging, i18n, common UI, templates, or operations automation for multiple product apps is created, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.small-service-platform-architecture-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Small Service Platform Architecture Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review a shared platform for many small products as an app factory, not as many copied services.
+
+The core question is: "Can a new product be added mostly by declaring product facts, while auth,
+billing, credits, entitlements, admin, analytics, observability, legal, deployment, and operations
+stay shared and explainable?" If not, the portfolio is just copy-paste debt with domains attached.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A repository, architecture plan, template, generator, or product platform is intended to support
+  many small apps, micro-SaaS products, SEO tools, AI tools, API products, downloads, extensions,
+  or similar product shells.
+- Code, docs, schemas, templates, or reviews touch a Product Registry, app catalog, shared account
+  portal, shared identity, organization, billing, credit ledger, usage meter, entitlement, admin,
+  analytics, logging, notification, i18n, legal, feature flag, app template, deployment factory,
+  file service, job queue, integration service, outbound webhook, AI Gateway, or license service.
+- A review or final report claims that creating another service is easy, the platform is reusable,
+  templates are shared, billing or credits are common, apps are tenant-safe, or operations can scale
+  beyond a few products.
+- A solo developer or small team wants to avoid reimplementing account, payment, admin, deploy,
+  telemetry, localization, support, and incident workflows for each product.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task concerns one standalone app with no multi-product platform, app factory, shared package,
+  or cross-product operational surface.
+- The task only changes a single auth flow, OAuth callback, session, token, or permission rule. Use
+  `auth-permission-change`, `auth-flow-triage`, or `api-access-control-review`.
+- The task only changes one payment, subscription, refund, webhook, credit, or usage path. Use
+  `payment-integrity-review` or `credit-ledger-integrity-review`.
+- The task only changes an admin screen, notification path, i18n path, deployment pipeline,
+  component library, AI feature, file upload, queue, or service boundary. Use the matching
+  specialist skill first.
+- The task is an organization-scale microservice split decision rather than a product-app factory.
+  Use `service-boundary-architecture` first.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal, target product count, product types, expected shared versus app-specific behavior,
+  repository layout, current diff or target files, and configured command intents.
+- Product Registry ledger: `app_id`, domains, environments, product names, auth modes, plan and
+  price mapping, entitlement keys, usage meters, credit costs, analytics namespace, admin panels,
+  i18n namespace, email templates, legal and consent versions, data categories, and deploy config.
+- Identity ledger: users, identities, sessions, organizations, workspaces, memberships, roles,
+  permissions, invitations, API keys, service accounts, account linking, and account portal scope.
+- Money and access ledger: customers, provider customers, subscriptions, invoices, tax profiles,
+  webhook events, refunds, disputes, wallets, credit grants, credit transactions, usage events,
+  reservations, quotas, limits, grace periods, and local entitlement state.
+- Operations ledger: support view, admin action log, resource change history, impersonation,
+  refunds, manual credits, feature overrides, account merge or delete, job logs, webhook logs,
+  email logs, runbooks, alerts, backups, and restore tests.
+- App factory ledger: app templates, `create-product` or equivalent generator, shared packages,
+  thin app shells, CI/CD, preview, staging, production, migration policy, smoke tests, rollback,
+  secrets, environment variables, DNS, TLS, CDN, storage, cache, queue, cron, and workers.
+- Observability and analytics ledger: event schema, first-value-created event, revenue metrics,
+  usage rollups, structured logs, traces, request IDs, app IDs, tenant IDs, alerts, status pages,
+  and cost monitors.
+- Shared product surface ledger: i18n, legal, consent, notifications, file service, job service,
+  integrations, outbound webhooks, SEO, marketing pages, shared UI, feature flags, remote config,
+  AI Gateway, license service, and developer portal where relevant.
+
+<!-- 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 platform, template, package, registry, billing, auth, admin, analytics, deploy,
+  and operations patterns have been searched before proposing a new platform layer.
+- If the change touches money, auth, privacy, admin, deployment, AI, localization, files, queues, or
+  notifications, also apply the narrower matching skill for that boundary.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Create or refine platform architecture docs, skill procedures, route metadata, templates, tests,
+  registry schemas, app factory contracts, shared package boundaries, operational runbooks, and
+  directly synchronized template copies tied to the multi-product platform surface.
+- Tighten platform boundaries by moving copied product logic into shared packages, registries,
+  policy services, ledgers, generators, runbooks, or explicit app-specific extension points.
+- Add focused tests for registry validation, entitlement resolution, credit ledger behavior,
+  webhook idempotency, template generation, app profile installation, admin permissions,
+  analytics event shape, i18n key coverage, smoke checks, and operation runbooks when existing
+  project patterns support them.
+- Do not migrate to a new cloud, framework, auth provider, billing provider, queue, database,
+  analytics tool, or orchestration platform unless the current task explicitly requires that
+  migration.
+- Do not turn every possible future product feature into mandatory platform scope. Separate the
+  phase-one spine from phase-two and phase-three extensions.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Decide whether this is a platform factory or a single product.
+   - A platform factory has several product shells, shared packages, shared ledgers, common
+     operations, and a path for adding a product through declaration plus thin app code.
+   - If the surface is one app, route to the narrower product or framework skill and report that
+     this skill does not apply.
+2. Build the Product Registry ledger first.
+   - Require one source of truth for app identity, domains, environments, auth policy, billing
+     catalog mapping, entitlement keys, usage meters, credit costs, analytics namespace, admin
+     panels, i18n namespace, email templates, legal versions, data categories, and deploy config.
+   - Flag product facts scattered across routes, Stripe dashboards, environment variables,
+     seed scripts, marketing pages, and app-specific constants.
+3. Review identity as a shared account operating system.
+   - Separate `User` from `Identity` so email, OAuth, passkeys, and account linking can evolve.
+   - Require common organization, workspace, membership, invitation, role, permission, API key,
+     service account, session management, device session, forced logout, and account portal paths.
+   - Keep billing, security, data export, data deletion, and login methods anchored in the account
+     portal even when product apps have their own settings.
+4. Review billing, entitlements, credits, and usage as local ledgers.
+   - Treat the payment provider as an event source, not as the application's only authority.
+   - Require provider webhooks to be stored, signature-checked, idempotent, replayable, and mapped
+     into local customer, subscription, invoice, refund, dispute, tax, and entitlement state.
+   - Reject feature gates such as `plan === "pro"`; require entitlement and limit checks.
+   - Reject balance-only credits; require append-only credit transactions, grants, usage events,
+     reservations, capture, release, partial capture, expiry, reconciliation, and audit evidence.
+5. Review admin and support as production control planes.
+   - Require a support view that connects user, organization, apps used, plan, payment state,
+     credit ledger, usage, recent errors, jobs, webhooks, notifications, experiments, and blocks.
+   - Separate audit logs from resource change history.
+   - Require scoped operator permissions, impersonation controls, dangerous-action confirmation,
+     reason capture, step-up authentication where needed, production guardrails, and PII masking.
+6. Review the app factory.
+   - Prefer a generator that registers a product and creates thin app shell files over a large
+     template copy that drifts.
+   - Keep shared auth, billing, credits, entitlements, analytics, logging, i18n, UI, email, jobs,
+     files, deployment, and support behavior in packages or services that remain upgradeable.
+   - Require templates for common product shapes only when they still depend on shared packages.
+7. Review deployment and database rollout.
+   - Require preview, staging, and production separation, environment-scoped secrets, provider
+     sandbox separation, migration checks, expand-migrate-contract sequencing, smoke tests,
+     rollback or rollback-forward runbooks, and post-deploy observation.
+   - Treat manual DNS, TLS, storage, queue, cron, backup, or monitoring setup as product launch
+     debt unless it is captured in a reproducible checklist or generator.
+8. Review analytics, logging, and operations before product count grows.
+   - Standardize event names, `app_id`, anonymous and authenticated user identity, tenant identity,
+     locale, country, campaign, plan, experiment, and request or trace identifiers.
+   - Require each product to declare its first-value-created event.
+   - Require structured logs, traces, alerts, dashboards, runbooks, backup checks, restore tests,
+     cost spike alerts, domain and certificate expiry alerts, job dead-letter handling, and webhook
+     replay.
+9. Review shared product surfaces.
+   - Keep notification categories, transactional versus marketing consent, i18n namespaces,
+     fallback behavior, legal and consent versions, shared UI layouts, file ownership, job
+     idempotency, integration tokens, outbound webhook signing, SEO templates, feature flags,
+     remote config, AI Gateway calls, and license keys common unless product-specific behavior is
+     deliberately declared.
+10. Review privacy and security as cross-product invariants.
+    - Require `app_id`, `tenant_id`, `user_id`, `request_id`, and `trace_id` on records where they
+      explain ownership, access, audit, or support.
+    - Require PII redaction, retention policy, consent records, cookie and marketing preferences,
+      data export, delete, anonymize, backup encryption, dependency scanning, abuse detection,
+      card-testing detection, and admin read audit for sensitive data.
+11. Phase the platform spine.
+    - Phase one should cover Product Registry, identity and organization, billing basics, credit
+      ledger, entitlement, basic admin, analytics events, structured logging, app template or
+      generator, CI/CD, and basic transactional email.
+    - Phase two should cover account portal depth, webhook replay, usage rollups, feature flags,
+      file service, job queue, support view, i18n, legal and consent, SEO templates, monitoring,
+      backups, and restore checks.
+    - Phase three should cover AI Gateway, affiliate or referral, license service, outbound
+      webhooks, developer portal, advanced experiments, advanced RBAC, warehouse, churn automation,
+      abuse detection, and cost optimization.
+12. Route specialist risks deliberately.
+    - Apply `payment-integrity-review`, `credit-ledger-integrity-review`,
+      `admin-control-plane-safety-review`, `notification-delivery-integrity-review`,
+      `frontend-localization-review`, `frontend-component-library-review`,
+      `deployment-rollout-safety-review`, `ai-product-readiness-review`,
+      `file-upload-security-review`, `queue-processing-integrity-review`, or
+      `service-boundary-architecture` when the platform review exposes a narrower implementation
+      risk.
+13. Report evidence level honestly.
+    - Separate architecture inspection, schema or registry evidence, package boundary evidence,
+      generated template evidence, test evidence, operational runbook evidence, provider webhook
+      fixture evidence, and real production-readiness evidence.
+    - Name missing configured intents or manual review for provider dashboards, cloud consoles,
+      browser smoke tests, visual review, or deployment checks instead of claiming readiness.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Product Registry, identity, billing, credit, entitlement, admin, app factory, deployment,
+  analytics, logging, shared product surface, security, privacy, operations, and phased rollout
+  ledgers are fixed, ruled out, or reported.
+- New product creation depends more on declared product facts and thin app code than on duplicated
+  auth, payment, admin, analytics, i18n, deployment, and operations code.
+- Product-specific behavior is declared as product-specific, and shared behavior has a clear owner.
+- Missing provider, deployment, telemetry, security, privacy, localization, or operational evidence
+  is named instead of hidden.
+
+<!-- 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`
+
+Use the narrowest configured unit, template, registry, docs, release, package, build, or mustflow
+intent that covers the changed platform contract. Do not infer provider dashboard, cloud console,
+deployment, browser, visual-regression, package-manager, or dev-server commands outside the command
+contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If no Product Registry or equivalent source of truth exists, stop treating the platform as
+  reusable and report the missing product authority.
+- If payment, credit, entitlement, or usage facts are split between provider dashboards and app
+  constants, apply the money and ledger specialist skills before claiming platform readiness.
+- If templates are copied but shared packages cannot be upgraded across product shells, report
+  template drift risk instead of calling the generator complete.
+- If admin or support paths require direct database edits, apply `admin-control-plane-safety-review`
+  and report the operational safety gap.
+- If verification fails, preserve the configured intent name and failure evidence, then fix the
+  platform contract surface rather than weakening tests or removing installed files.
+- If release impact is unclear, apply `date-number-audit` before editing versions or release notes.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Platform surface reviewed
+- Product Registry, identity, billing, credit, entitlement, admin, app factory, deployment,
+  analytics, observability, shared surface, security, privacy, operations, and phase ledgers
+- Findings, fixes, or recommendations
+- Shared versus product-specific ownership decisions
+- Specialist skills used or deferred
+- Evidence level by registry, schema, package, template, tests, provider, deployment, telemetry,
+  and runbook surface
+- Command intents run
+- Skipped platform-readiness checks and reasons
+- Remaining small-service platform architecture risk

package/templates/default/locales/en/.mustflow/skills/tauri-code-change/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.tauri-code-change
 locale: en
 canonical: true
-revision: 3
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: tauri-code-change
-description: Apply this skill when Tauri frontend invokes, Rust commands, capabilities, permissions, scopes, plugins, filesystem, dialog, shell, opener, updater, sidecar, or mobile native permissions are created or changed.
+description: Apply this skill when Tauri frontend invokes, Rust commands, capabilities, permissions, scopes, plugins, filesystem, dialog, shell, opener, updater, sidecar, mobile native permissions, Tauri bundling targets, release package formats, or native desktop CI build matrices are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -38,6 +38,8 @@ Treat the WebView as low trust and the Rust/native side as high authority. Front
 - `src-tauri`, `tauri.conf.*`, `Cargo.toml`, `#[tauri::command]`, `invoke`, Tauri JavaScript APIs, plugin config, capabilities, permissions, scopes, CSP, WebView bootstrap HTML, fs, dialog, shell, opener, updater, sidecar, mobile manifests, or native permissions change.
 - A frontend button, menu, or workflow calls native resources through Tauri.
 - A packaged Tauri app shows a blank or black WebView after release and browser console or built HTML may point to Content Security Policy blocking the frontend bootstrap.
+- Tauri release packaging, `bundle.targets`, platform target triples, updater artifacts, signing,
+  or CI matrix behavior changes.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -49,6 +51,9 @@ Treat the WebView as low trust and the Rust/native side as high authority. Front
 ## Required Inputs
 
 - Frontend package metadata, static build output or generated entry HTML, Tauri config, Rust manifests, main/lib command modules, command registration, capability and permission files, plugin config, updater config, sidecar config, mobile permissions, and tests.
+- Build and release evidence when packaging is in scope: CI workflow or task definitions, runner
+  OS matrix, package formats, `bundle.targets`, Rust and frontend cache strategy, signing or
+  notarization gates, updater artifacts, artifact retention, and release asset upload path.
 - Map of frontend calls to Rust commands or plugin APIs, permission scopes, exact window labels, exact webview labels, CSP directives, remote origins, WebView custom protocols or IPC origins, and actual OS resources.
 - Permission diff: previous permissions, new permissions, newly reachable windows/webviews, new scopes, and native operations enabled.
 - Configured verification intents.
@@ -69,6 +74,8 @@ Treat the WebView as low trust and the Rust/native side as high authority. Front
 - Prefer app-owned directories and stable app IDs over broad filesystem paths.
 - Keep shell, opener, sidecar, and updater behavior narrowly scoped.
 - Prefer Rust commands that map small enums or ids to fixed native operations over exposing broad plugin APIs directly to the frontend.
+- Keep package target lists explicit. Do not rely on broad "all targets" behavior when the product
+  only ships a small set of installers or archives.
 
 <!-- mustflow-section: procedure -->
 ## Procedure
@@ -81,7 +88,9 @@ Treat the WebView as low trust and the Rust/native side as high authority. Front
 6. Apply the CSP and WebView bootstrap policy below before tightening `script-src`, `connect-src`, `style-src`, `worker-src`, `img-src`, `font-src`, or remote-origin policy.
 7. Apply the command input policy below before adding or changing `#[tauri::command]` handlers or `invoke` wrappers.
 8. Apply the filesystem, dialog, shell, opener, updater, and sidecar policies below when those plugins or native operations are touched.
-9. Choose configured verification intents that cover Rust, frontend, Tauri build, permission/capability drift, CSP behavior, and security-sensitive behavior when available.
+9. Apply the build and release matrix policy below when `tauri.conf.*`, release scripts, CI
+   workflows, updater artifacts, signing, or bundle targets change.
+10. Choose configured verification intents that cover Rust, frontend, Tauri build, permission/capability drift, CSP behavior, and security-sensitive behavior when available.
 
 ## Capability And Permission Policy
 
@@ -138,6 +147,28 @@ Treat the WebView as low trust and the Rust/native side as high authority. Front
 - Frontend update input may select only a closed channel enum when needed. Rust or static config must map that enum to hard-coded HTTPS endpoints and configured public keys.
 - Do not enable insecure updater transport in production unless the user explicitly accepts the supply-chain boundary change and the repository records why.
 
+## Build And Release Matrix Policy
+
+- Treat Tauri release builds as Rust release builds plus frontend build plus bundling. Cold Cargo
+  builds can dominate CI time, so check Rust cache, Node or package-manager cache, lockfile keys,
+  and target-specific cache dimensions before blaming frontend code.
+- Do not run full native bundles for every pull request by default. Prefer PR checks that prove the
+  frontend build, Rust compile or checks, command contracts, and permission files on the cheapest
+  adequate runner. Reserve full Windows, Linux, macOS, signing, notarization, updater, and installer
+  matrices for release tags, release branches, or protected manual gates unless the repository
+  explicitly requires more.
+- Keep `bundle.targets` or equivalent packaging configuration to the formats actually shipped. Do
+  not leave broad all-format packaging enabled when the release only needs, for example, one Windows
+  installer, one macOS disk image or app bundle, and one Linux package format.
+- For macOS distribution, prefer one deliberate universal or architecture-specific strategy rather
+  than accidental duplicate jobs. Name signing and notarization boundaries separately from compile
+  time.
+- Keep test artifacts short-lived and promote durable distributables through the release or package
+  channel. Do not use long-retention CI artifacts as the canonical release surface.
+- If a cost comparison between Tauri and another desktop stack is requested, route the CI billing,
+  runner-minute, artifact-storage, and matrix-shape analysis through `ci-pipeline-triage`; use this
+  skill for Tauri-specific bundle targets, Cargo cache, updater, signing, and packaging behavior.
+
 ## Review Rejection Criteria
 
 Reject or revise a change when:
@@ -163,6 +194,8 @@ Reject or revise a change when:
 - Permission and capability changes have a clear diff and native-operation justification.
 - CSP changes have been checked against the generated frontend entry HTML and required Tauri IPC or custom protocol origins.
 - Missing Tauri-specific verification is reported.
+- Tauri package targets, release matrix, cache strategy, and artifact retention are explicit when
+  packaging is touched.
 
 <!-- mustflow-section: verification -->
 ## Verification
@@ -188,6 +221,9 @@ Report missing native build, packaged WebView smoke, CSP violation, permission d
 - If a CSP change breaks packaged app startup, inspect generated HTML and console CSP violations before widening policy; prefer nonce, hash, or externalized bootstrap before accepting `unsafe-inline`.
 - If a command accepts broad input, replace it with a typed request and Rust-side validation before exposing it to the frontend.
 - If updater, shell, opener, sidecar, or filesystem access cannot be narrowed, report the security boundary change instead of hiding it as a normal feature fix.
+- If packaging cost or duration grows unexpectedly, check `bundle.targets`, release-only matrix
+  gating, Rust cache, frontend cache, macOS job count, signing and notarization split, and artifact
+  retention before changing unrelated app code.
 
 <!-- mustflow-section: output-format -->
 ## Output Format
@@ -196,6 +232,8 @@ Report missing native build, packaged WebView smoke, CSP violation, permission d
 - IPC, command input, CSP, permission, capability, window/webview, and scope notes
 - Permission diff: old permissions, new permissions, newly reachable windows/webviews, new scopes, and native operation justification
 - Filesystem, dialog, shell, opener, updater, sidecar, or mobile risk
+- Build matrix, bundle target, signing or notarization, cache, artifact retention, and release asset
+  notes when packaging is touched
 - Files changed
 - Command intents run
 - Skipped checks and reasons