mustflow 2.116.4 → 2.117.1

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.credit-ledger-integrity-review
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: credit-ledger-integrity-review
-description: Apply this skill when credits, points, wallet balances, reward points, prepaid credits, usage credits, bonus credits, loyalty points, stored-value balances, balance deductions, accruals, refunds, reversals, expirations, reservations, captures, releases, admin adjustments, ledger tables, balance caches, reconciliation jobs, settlement reports, or credit-related tests need review for ledger integrity, idempotency, atomic balance changes, concurrency, ordering, ownership, amount precision, policy snapshots, expiry lots, failure recovery, audit evidence, or reconciliation risk.
+description: Apply this skill when credits, points, wallet balances, reward points, prepaid credits, usage credits, bonus credits, loyalty points, stored-value balances, purchased versus subscription or promotional balance classes, balance deductions, accruals, refunds, reversals, expirations, rollovers, price quotes, reservations, captures, releases, admin adjustments, ledger tables, balance caches, reconciliation jobs, settlement reports, or credit-related tests need review for ledger integrity, idempotency, atomic balance changes, concurrency, ordering, ownership, amount precision, policy snapshots, expiry lots, quote binding, failure recovery, audit evidence, or reconciliation risk.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -60,7 +60,9 @@ Review credit, point, and wallet balance code as an accounting ledger, not a bal
 - Amount and unit ledger: integer unit or decimal representation, maximum amount, rounding rules, conversion rates, bonus rules, policy version, product price snapshot, and campaign snapshot.
 - Ownership ledger: user, tenant, wallet, account, team, family, organization, operator, source object, and current actor checks.
 - Expiry and lot ledger: FIFO, LIFO, earliest-expiry-first, bucket allocation, expiry batch, lot-level consumption, partial use, partial refund, and lot restoration behavior.
+- Balance-rights ledger: purchased top-up, subscription-included, promotional, referral, trial, enterprise commitment, refund, or admin-grant source; acquisition and policy version; expiry and rollover right; cancellation or downgrade behavior; legal or platform constraint; and spend priority.
 - Reservation ledger: reserved, captured, released, failed, expired, cancelled, partially refunded, and reversed states, plus the owner of each transition.
+- Quote and fulfillment ledger: `quote_id`, price version, input-parameter hash, exact or bounded estimate, maximum authorized amount, quote expiry, reservation identity, actual captured amount, usable-result predicate, partial-result rule, and release or refund evidence.
 - Queue and cache ledger: producer events, consumer idempotency, partitioning, outbox or inbox records, read-replica routing, cache invalidation, and balance display semantics.
 - Audit and reconciliation ledger: logs, metrics, support IDs, before/after values, daily balance-vs-ledger checks, settlement reports, and manual adjustment evidence.
 
@@ -97,9 +99,11 @@ Review credit, point, and wallet balance code as an accounting ledger, not a bal
 14. Model refunds as reversals. Refunds, cancellations, and corrections should reference the original ledger entry or reservation, not call a generic balance increase with no causal link.
 15. Test partial use and partial refund. Exercise cases where only part of a balance, lot, coupon, order, or mixed payment is used or refunded. Full-cancel-only assumptions are not enough.
 16. Consume expiry lots deliberately. When credits expire, inspect FIFO, LIFO, earliest-expiry-first, or policy-specific lot allocation. Record lot-level consumption so later refund and audit can reconstruct the path.
+    - Keep purchased top-up, subscription-included, promotional, trial, enterprise, and admin-grant lots distinct when their expiry, rollover, cancellation, refund, accounting, or platform rights differ. Do not collapse them into one balance and reconstruct ownership from current plan state.
 17. Race expiry and usage. Expiry batches must use the same ledger, lock, idempotency, and conditional update rules as user requests. Flag direct batch subtraction that bypasses wallet safeguards.
 18. Separate reservation from capture. Model reserved, captured, released, failed, expired, cancelled, and partially refunded states when credits are held before final purchase, fulfillment, or external payment completion.
     - This ledger owns atomic reserve, capture, and release and the balance invariant. Commands and durable workflows may consume those operations but must not redefine balance availability, ownership, or accounting transitions.
+    - Bind a reservation to an unexpired user-visible quote and immutable price snapshot. Reserve no more than the approved maximum, capture only the actual charge allowed by the quoted policy and usable-result predicate, and release the remainder on failure, cancellation, timeout recovery, or lower actual usage.
 19. Draw allowed state transitions. Prevent arbitrary `status = REFUNDED`, `status = CAPTURED`, or `status = EXPIRED` writes. Each transition should have a guard, cause, effect, and idempotency rule.
 20. Preserve queue ordering or tolerate reordering. If deduction, cancellation, refund, or expiry events use a queue, prove user, wallet, or transaction-level ordering, or make each consumer robust to reordered events.
 21. Treat message redelivery as normal. Producers, queues, schedulers, and webhooks can duplicate events. Consumer-side ledger mutation must be idempotent with durable dedupe records.
@@ -116,7 +120,7 @@ Review credit, point, and wallet balance code as an accounting ledger, not a bal
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
-- The credit surface has balance, ledger-entry, source identity, atomicity, amount/unit, ownership, expiry/lot, reservation, queue/cache, audit, and reconciliation maps.
+- The credit surface has balance, ledger-entry, source identity, atomicity, amount/unit, ownership, balance-rights, expiry/lot, quote/fulfillment, reservation, queue/cache, audit, and reconciliation maps.
 - Any mutable-balance-only path, missing source key, weak idempotency comparison, non-atomic deduction, wrong lock target, float amount, hidden rounding policy, missing DB invariant, duplicate ledger risk, generic refund, expiry race, cache-trusted deduction, stale replica read, unaudited admin adjustment, or missing reconciliation is fixed or reported with evidence.
 - Tests or explicit verification cover the highest-risk concurrency, failure, duplicate, expiry, reservation, refund, cache, and reconciliation paths available in the current scope.
 - Soft operational budgets remain outside this ledger unless they represent prepaid or money-equivalent value.
@@ -152,7 +156,7 @@ Prefer focused tests for concurrent deductions, duplicate idempotency keys, affe
 ## Output Format
 
 - Credit or wallet surface reviewed
-- Balance, ledger-entry, source identity, atomicity, amount/unit, ownership, expiry/lot, reservation, queue/cache, audit, and reconciliation ledgers
+- Balance, ledger-entry, source identity, atomicity, amount/unit, ownership, balance-rights, expiry/lot, quote/fulfillment, reservation, queue/cache, audit, and reconciliation ledgers
 - Findings or fixes for duplicate, concurrent, wrong-owner, wrong-amount, rounding, expiry, reservation, refund, cache, replica, failure-recovery, admin, and reconciliation risks
 - Nightmare-path tests or evidence added, run, skipped, or still missing
 - Command intents run

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

@@ -0,0 +1,283 @@
+---
+mustflow_doc: skill.credit-monetization-integrity-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: credit-monetization-integrity-review
+description: Apply this skill when a product changes credit-pack offers, offer timing, price-discount versus bonus-credit framing, pack count or spacing, first-purchase recommendations, purchased-credit expiry, subscription-credit rollover, promotional balances, spend order, credit price disclosure, variable-cost estimates, quote and reservation UX, breakage, repurchase, retention, or credit-monetization experiments and must optimize long-horizon contribution without deceptive equivalence, balance-rights drift, surprise deductions, or survivor-biased metrics.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.credit-monetization-integrity-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Credit Monetization Integrity Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Sell and spend product credits without optimizing a checkout click, early breakage, or raw execution
+count at the expense of customer rights, useful output, repurchase, retention, or long-horizon
+contribution. Keep offer design, balance-class policy, user-visible price authorization, technical
+ledger integrity, payment processing, accounting, and legal or platform compliance as connected but
+separately owned contracts.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A credit or usage-pack offer changes timing, trigger, eligibility, discount, bonus, limit, expiry,
+  urgency, recommendation, or first-purchase treatment.
+- A product compares price-discount and bonus-credit framing or changes how credits translate into
+  images, minutes, tasks, API calls, documents, generations, or other user-recognizable output.
+- The first-purchase screen changes between three, five, seven, custom, tiered, decoy, anchored, or
+  recommended credit packs, or changes price and unit-price spacing.
+- Purchased top-up, subscription-included, promotional, referral, trial, refund, or enterprise
+  credits change expiry, rollover, cancellation, downgrade, transfer, refund, or spend-order policy.
+- A feature changes from hidden or post-execution deduction to an exact or bounded pre-execution
+  quote, maximum authorization, reservation, success-based capture, partial settlement, or release.
+- Credit conversion, repurchase, breakage, retained use, contribution, variable cost, refund, support,
+  or experiment definitions are created, changed, reviewed, or reported.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The main risk is atomic balance mutation, lot allocation, reservation state, idempotency,
+  concurrency, expiry races, refunds, reconciliation, or admin adjustment; use
+  `credit-ledger-integrity-review` as the technical owner.
+- The main risk is checkout, provider payment, tax, invoice, receipt, refund, dispute, chargeback,
+  fraud, or payment webhook correctness; use `payment-integrity-review`.
+- The main risk is cancellation, pause, downgrade, dormant-user win-back, or save-offer profit; use
+  `subscription-retention-profit-review`.
+- The main risk is signup, pre-account activation, first-owned value, or onboarding questions without
+  a credit purchase or spend policy; use `product-onboarding-activation-review`.
+- The task only estimates internal model or compute cost and does not change a user credit right,
+  price, purchase, or deduction; use the matching cost-control skill.
+- The task requests jurisdiction-specific legal, tax, accounting, or unclaimed-property advice. Use
+  qualified authority and current primary rules; this skill supplies the product evidence packet but
+  does not decide legal classification.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Eligible-cohort ledger: eligibility, assignment unit and time, holdout, exposure, offer trigger,
+  identity joins, exclusions, prior-purchase state, product-value state, traffic, and denominator.
+- Offer ledger: offer version, trigger, surface, interruption cost, real start and expiry, pack scope,
+  discount or bonus, cap, eligibility, cooldown, price history, and suppression.
+- Value and usage ledger: first owned result, recognizable output units, free and paid usage, expected
+  cadence, depletion, active-user usage distribution, useful-result rate, and abandoned or failed use.
+- Pack ledger: price, credits, unit price, output-equivalent range, variable cost, margin, recommended
+  segment, lower and upper alternatives, custom amount, refundability, and historical selection.
+- Balance-rights ledger: acquisition class, consideration paid, policy and price version, expiry,
+  rollover, cancellation or downgrade behavior, refund, transfer, spend priority, platform rule,
+  jurisdiction review, and accounting treatment.
+- Quote and execution ledger: input parameters, exact or estimated charge, estimate range, maximum
+  authorization, quote ID and expiry, price version, reservation, actual charge, usable-result
+  predicate, partial-result rule, release, reversal, and retry identity.
+- Economics ledger: cash collected, payment and refund cost, variable service cost, support and
+  dispute cost, bonus liability, deferred or recognized revenue boundary, breakage, repurchase,
+  retention, and contribution per eligible unit over declared horizons.
+- Experiment ledger: control and variants, sequencing, power assumptions, exposure integrity,
+  cannibalization, stockpiling, delayed repurchase, guardrails, segment policy, and promotion rule.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Define the user-owned value event, balance classes, and usable-result predicate before changing an
+  offer, expiry, rollover, pack, or deduction policy.
+- Assign experiments before a behavior-dependent offer trigger. Keep assigned users who never reach
+  the trigger in the intent-to-treat denominator, while recording trigger reach and exposure
+  separately.
+- Refresh current platform, app-store, jurisdiction, contract, accounting, and tax constraints before
+  changing purchased-value expiry, cancellation forfeiture, restore, refund, or price representation.
+- Treat vendor policies, academic studies, benchmark rates, sample prices, pack ratios, and another
+  product's rollover cap as hypotheses or comparators, not repository defaults.
+- Keep command execution under `.mustflow/config/commands.toml`; this skill does not authorize live
+  price changes, promotions, balance mutations, payments, messages, experiments, or legal filings.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or refine offer eligibility and timing, equivalent-value calculation, pack construction and
+  recommendation, output-unit translations, balance-class policy, expiry and rollover rules,
+  user-visible quote and authorization, contribution metrics, experiment assignment, guardrails,
+  fixtures, tests, docs, route metadata, and synchronized templates.
+- Add explicit handoffs to credit-ledger, payment, accounting, tax, privacy, consumer-protection, or
+  platform review when those owners must implement or approve the policy.
+- Remove fake urgency, economically unequal framing tests presented as copy tests, dominated decoy
+  packs, hidden deductions, unsupported exact estimates, or breakage targets that reward unused value.
+- Do not retroactively rewrite purchased rights, expire balances contrary to an applicable platform
+  or legal rule, hide a required total price, or capture credits for an unusable result merely because
+  an internal provider incurred cost.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Separate six decisions: offer timing, economic framing, pack architecture, balance rights,
+   user-visible spend authorization, and ledger settlement. Do not let one winning purchase metric
+   silently choose the other five.
+2. Define the headline outcome per eligible assigned user. Prefer incremental contribution over a
+   declared short and long horizon, supported by paid conversion, useful paid output, depletion-
+   adjusted repurchase, retained use, refunds, disputes, support, and variable cost. Treat offer open,
+   checkout start, raw purchase rate, raw executions, and breakage as diagnostic events.
+3. Randomize before the offer can become eligible. Compare a no-offer or business-as-usual holdout
+   with bounded timing policies such as account completion, first owned value, a declared depletion
+   state, or a time-based reminder. Do not analyze only users who reached first success or depleted a
+   free balance.
+4. Price interruption cost. Before value, a full-screen offer can block activation; after value, an
+   offer may extend a proven job; near depletion, exposed users are fewer but intent may be stronger.
+   Preserve a nonblocking path and do not copy a universal best trigger.
+5. Anchor any real deadline to the event that creates eligibility and disclose the exact expiry.
+   Preserve the offer after refresh and across devices when promised. Do not restart countdowns,
+   invent scarcity, or begin a value-dependent offer before the user could receive value.
+6. Normalize economic value before testing copy. For price discount `d`, the paid unit-price factor
+   is `1 - d`. For bonus fraction `b`, it is `1 / (1 + b)` and the effective unit discount is
+   `b / (1 + b)`. An equivalent bonus for discount `d` is `d / (1 - d)`. Hold unit economics equal
+   when the question is framing, or label the test as an offer-value test.
+7. Translate credits into user-recognizable output. Show total credits, unit price or savings, and a
+   bounded result-equivalent derived from current product prices. Use ranges when input length,
+   duration, model, quality, or external calls vary; do not promise one exact output count from an
+   unstable mix.
+8. Measure bonus inventory correctly. Extra credits can delay the next purchase without reducing
+   satisfaction. Track consumption velocity, balance depletion, repurchase after comparable
+   depletion, cumulative cash, contribution, and retained useful output rather than declaring an
+   early repurchase decline a retention failure.
+9. Price promotional cannibalization and stockpiling. Include buyers who would have paid full price,
+   bonus credits actually consumed, future purchases displaced, refund and support cost, and heavy
+   users who pull demand forward. Cap scope from observed economics, not a universal percentage.
+10. Build pack candidates from usage and willingness evidence. Use the lower pack for safe entry, the
+    recommended pack for a declared typical segment or task horizon, and the upper pack for genuine
+    high usage. Price gaps, credit gaps, and unit discounts must be legible and economically viable.
+11. Start with the smallest pack set that represents materially different jobs. Three packs are a
+    useful first-purchase hypothesis, not a law. Compare three with five when added tiers map to real
+    segments; expose more tiers or custom amounts to repeat or high-variance buyers when evidence
+    supports them. Do not add seven merely to create an anchor.
+12. Reject fake decoys. A deliberately dominated pack can make the entire credit system look
+    manipulated. Each displayed pack needs a plausible buyer, a clear output-equivalent, and a reason
+    to exist other than making another pack look cheap.
+13. Keep recommendation honest. Name the usage basis, avoid preselecting a pack that exceeds the
+    represented need, make every alternative and unit price visible, and measure regret, refunds,
+    support, depletion, and repeat purchase by selected pack.
+14. Classify every balance lot by acquired right. Separate purchased top-up, subscription-included,
+    promotional or referral, trial, refund, enterprise commitment, and admin grant when consideration,
+    expiry, rollover, restore, cancellation, accounting, platform, or legal rights differ.
+15. Do not treat purchased-credit expiry as free margin. Cash arrives at purchase; unused rights can
+    change future service cost and revenue recognition but can also reduce conversion, trust,
+    repurchase, and retained value. Compare lawful policy variants by long-horizon contribution and
+    never use breakage alone as the objective.
+16. Gate expiry through current authority. Record platform and jurisdiction, product classification,
+    customer type, contract version, notice, restore, refund, inactivity, unclaimed-property, and
+    accounting treatment. If authority is unresolved, preserve the more durable purchased right and
+    keep promotional or subscription policy separate rather than guessing.
+17. Derive subscription rollover from cost and retention evidence. Compare full reset, bounded
+    rollover, and other lawful policies using maximum liability, usage bursts, concurrency, capacity,
+    cancellation or downgrade behavior, and long-horizon cohort contribution. A one-cycle or
+    multiple-of-quota cap is a candidate, not a universal default.
+18. Spend lots by explicit rights. Prefer the balance that would lawfully expire sooner when doing so
+    preserves user value, but keep refunds, tax, enterprise commitments, negative balances, plan
+    changes, and policy snapshots reconstructable. Never consume durable purchased value first merely
+    to manufacture subscription breakage.
+19. Preserve price-version meaning. Snapshot the feature price, pack price, bonus, output-equivalent,
+    policy, and conversion rule used at purchase and execution. Review whether later feature-price
+    changes lawfully alter old credit purchasing power; do not hide retroactive devaluation behind a
+    nominally unchanged balance.
+20. Show spend before execution. Display an exact charge when inputs fix the cost. Otherwise show a
+    defensible range and maximum authorization, the factors that can change it, remaining balance,
+    and what happens on failure or cancellation. Price visibility need not require a blocking modal
+    for every low-cost repeat action.
+21. Use a quote-reserve-settle flow. Create an expiring `quote_id` bound to actor, product, input hash,
+    price version, policy, exact or maximum amount, and idempotency identity; reserve atomically;
+    execute once; capture the allowed actual amount for a usable result; and release the remainder on
+    lower usage, failure, cancellation, or recovered timeout. Route ledger correctness through
+    `credit-ledger-integrity-review`.
+22. Define usable and partial results before charging. Distinguish full success, declared partial
+    value, user cancellation, safety refusal, provider failure, product defect, timeout with unknown
+    outcome, and duplicate retry. Internal compute cost does not by itself prove customer value or
+    authorize a deduction.
+23. Add confirmation only when consequence warrants it. Consider spend share, cash top-up, unusual
+    model or quality, irreversible output, variable maximum, or first use. Let users remember a safe
+    choice with an accessible way to inspect and change it; do not copy a universal balance percentage.
+24. Separate product, ledger, payment, and accounting evidence. A product experiment can recommend a
+    policy but cannot prove atomic balances, provider settlement, tax treatment, or revenue
+    recognition. Require the matching specialist evidence before reporting the full system ready.
+25. Predeclare guardrails and analysis. Include activation interruption, useful-output rate, latency,
+    stockpiling, depletion, unit cost, p95 cost, refunds, support, disputes, accessibility, platform
+    rejection, legal review, accounting uncertainty, and segment heterogeneity. Correct repeated
+    peeking and do not ship a post-hoc segment as established.
+26. Promote only a reversible policy whose eligible-cohort contribution improves without violating
+    purchased rights, transparent pricing, useful-result charging, ledger integrity, or platform and
+    legal constraints. Preserve old policy snapshots and a rollback path for future transactions.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Offer timing uses pre-trigger assignment, a holdout, an eligible-cohort denominator, and both
+  activation and long-horizon contribution guardrails.
+- Discount and bonus framing is compared at equal unit economics or explicitly labeled unequal.
+- Pack count and spacing follow real usage segments, legible unit economics, and non-dominated jobs
+  rather than a universal tier count or copied price ratio.
+- Purchased, subscription, promotional, trial, enterprise, refund, and admin balances retain distinct
+  policy snapshots, expiry or rollover rights, and spend order where their contracts differ.
+- Expiry and rollover decisions name current platform, jurisdiction, accounting, cost, capacity,
+  cancellation, and long-horizon retention evidence or remain unresolved.
+- Every execution shows an exact or bounded price before authorization and settles a quote through
+  reserve, usable-result capture, and release or reversal.
+- Breakage, raw execution, checkout start, and trigger-reached conversion remain diagnostics rather
+  than standalone proof of monetization success.
+
+<!-- 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`, and `mustflow_check`.
+Do not infer raw analytics, warehouse, payment-provider, balance-mutation, accounting, experiment,
+deployment, or production commands.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If discount and bonus variants have different unit economics, stop calling the result a framing
+  effect and report the actual effective discount and margin difference.
+- If assignment begins after first value or depletion, report trigger-conditioned evidence and do
+  not generalize it to the eligible signup or visitor cohort.
+- If traffic cannot support timing, framing, and pack tests together, sequence them and keep the
+  remaining decisions as hypotheses rather than bundling mechanisms into one opaque variant.
+- If purchased-right expiry or cancellation forfeiture lacks current platform, jurisdiction,
+  contract, and accounting evidence, preserve the existing durable right and route the decision to
+  qualified authority.
+- If balance classes cannot be reconstructed, do not introduce a new expiry, rollover, or spend-order
+  policy until the ledger can preserve acquisition source and policy version.
+- If a variable-cost action cannot produce a defensible estimate, set a conservative authorized
+  maximum or block the paid path; do not advertise fake precision or surprise-charge afterward.
+- If execution outcome is unknown, keep the reservation pending or reconcile it under a bounded
+  policy; do not capture or release based only on a client timeout.
+- If short-horizon purchase or breakage rises while useful output, contribution, repurchase,
+  retention, refunds, disputes, support, or trust guardrails worsen, reject or narrow the treatment.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Eligible cohort, assignment, trigger, exposure, holdout, and denominator
+- Offer timing, interruption, urgency, eligibility, and suppression decision
+- Discount and bonus economic-equivalence calculation and framing result
+- Pack count, segment, output-equivalent, price spacing, recommendation, and margin decision
+- Balance classes, purchased rights, expiry, rollover, cancellation, restore, and spend-order policy
+- Exact or bounded quote, maximum authorization, reserve, usable-result capture, and release contract
+- Short- and long-horizon contribution, depletion-adjusted repurchase, cost, refund, support, dispute,
+  activation, retention, platform, legal, accounting, and trust evidence
+- Files changed
+- Command intents run and skipped checks
+- Remaining credit-monetization risk
+

package/templates/default/locales/en/.mustflow/skills/desktop-commercial-distribution-review/SKILL.md

@@ -0,0 +1,225 @@
+---
+mustflow_doc: skill.desktop-commercial-distribution-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: desktop-commercial-distribution-review
+description: Apply this skill when a commercial desktop app changes direct download versus Microsoft Store or Mac App Store distribution, hybrid store and website availability, store versus external commerce, channel fees and net receipts, installation trust, signing or notarization cost, sandbox and capability fit, discovery, checkout conversion, trials and licenses, purchase restoration, entitlement portability, update-channel ownership, review delay, enterprise or offline distribution, channel-specific support, or retained contribution and must choose distribution without forking the product or relying on stale store policy.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.desktop-commercial-distribution-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Desktop Commercial Distribution Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Choose direct, store, or hybrid desktop distribution from platform fit, customer trust, commerce,
+licensing, update ownership, support cost, and incremental contribution. Keep one product contract
+while channel adapters satisfy different packaging and policy boundaries.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A Windows or macOS desktop app compares website download, Microsoft Store, Mac App Store, another
+  approved storefront, managed enterprise distribution, or a hybrid channel strategy.
+- The app compares store commerce with external checkout, subscription, perpetual license, paid
+  upgrade, coupon, bundle, team license, or customer account entitlements.
+- Store fees, payment processing, tax handling, refunds, chargebacks, discovery, trust, code signing,
+  notarization, malware reputation, sandboxing, review delay, updates, analytics, or support change.
+- Direct and store builds differ in capabilities, installers, licensing, account login, trial,
+  restore, update mechanism, plugins, automation, background services, or enterprise deployment.
+- A report claims one channel produces better conversion, lower fees, easier updates, more trust, or
+  higher retained contribution.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only changes updater feeds, signatures, immutable artifacts, staged rollout, old-version
+  upgrades, relaunch, or update telemetry; use `desktop-auto-update-safety-review`.
+- The task only changes packaging, signing, notarization, release assets, publication, or installed
+  smoke tests with a distribution channel already chosen; use the matching release, packaging, and
+  platform skills.
+- The task only changes checkout, payment webhooks, tax, refund, dispute, or entitlement correctness
+  independent of desktop channel choice; use `payment-integrity-review`.
+- The task only changes generic subscription, trial, price, regional pricing, or bundle economics;
+  use `pricing-model-integrity-review` or `product-portfolio-integrity-review`.
+- The task requests current platform-law interpretation or contract advice. Use official current
+  platform terms and qualified authority; this skill supplies the comparison packet.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Product ledger: audience, buyer, price and cadence, core job, platform targets, capability and
+  privilege needs, plugins or extensions, background services, local files, enterprise needs,
+  offline use, support model, and expected update cadence.
+- Channel ledger: platform, storefront or website, app type, packaging, sandbox, capability,
+  signing, notarization, review, listing, regions, discovery, install trust, trial, commerce,
+  entitlement, restore, update, rollback, analytics, ratings, support, and policy version.
+- Economics ledger: gross price, store share, payment processing, fixed transaction fee, tax and
+  merchant-of-record cost, refund, chargeback, fraud, signing, hosting, bandwidth, review delay,
+  update operation, support, acquisition, retained revenue, and contribution.
+- Identity and license ledger: product account, store account, transaction identity, receipt,
+  license, device or seat, organization, entitlement source, restore, refund, revocation, migration,
+  offline lease, and customer support lookup.
+- Build ledger: common core, channel adapter, feature flags, packaging, commerce adapter, license
+  adapter, update adapter, policy differences, artifact identity, version, tests, and drift owner.
+- Experiment ledger: eligible buyer, acquisition source, channel availability, exposure, self-
+  selection, price and package parity, platform and region, install, purchase, activation, refund,
+  retained use, support, and promotion rule.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Separate listing and discovery, binary distribution, checkout, entitlement, update, and support.
+  One channel need not own every layer.
+- Identify app type and current platform policy before assuming fees, external commerce, sandbox,
+  signing, entitlement, or update rules.
+- Define one product identity and accepted entitlement before adding channel-specific adapters.
+- Treat copied fee percentages, registration costs, conversion lifts, review times, platform defaults,
+  and break-even thresholds as dated inputs, not built-in policy.
+- This skill does not authorize developer enrollment, contract acceptance, store submission,
+  signing-key access, notarization, publication, price changes, live checkout, migration, or release.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or refine channel policy, capability and sandbox matrix, direct and store packaging boundaries,
+  commerce and license adapters, purchase restoration, entitlement portability, update ownership,
+  channel economics, experiments, fixtures, tests, docs, route metadata, and synchronized templates.
+- Add explicit handoffs to platform, packaging, signing, notarization, updater, payment, tax,
+  accounting, licensing, security, privacy, enterprise distribution, or legal owners.
+- Replace a forked product, gross-fee comparison, store-discovery assumption, download-as-conversion,
+  or channel-specific customer orphaning with shared contracts and full-funnel evidence.
+- Do not bypass store rules, weaken signing or sandbox security, hide channel limitations, duplicate
+  purchases silently, or promise license portability that current receipts and contracts cannot
+  provide.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Split six decisions: discovery, binary delivery, checkout, entitlement, updates, and support.
+   Compare direct, store, and hybrid combinations rather than forcing one channel to own all six.
+2. Classify the app before comparing channels. Include consumer versus professional buyer, price,
+   subscription or perpetual rights, system access, automation, plugins, background services,
+   enterprise deployment, offline use, and support burden.
+3. Refresh official platform policy by date, app type, commerce type, region, and program. A current
+   non-game exception, external-link entitlement, fee, enrollment rule, or sandbox requirement does
+   not automatically apply to games, another region, or a future release.
+4. Build a capability matrix. Mark which features work unchanged, need an entitlement or review,
+   require a channel adapter, degrade under sandboxing, or make the channel infeasible. Do not ship a
+   trusted but materially crippled store build without clear disclosure.
+5. Compare installation trust honestly. Include code signing, notarization, reputation warnings,
+   malware scanning, hosted delivery, review, publisher identity, account trust, and enterprise
+   policy; a store badge and a signed direct binary provide different evidence.
+6. Compare discovery as incremental acquisition, not storefront presence. Track listing views,
+   qualified installs, first owned value, purchase, retained use, and customers who would have found
+   the website anyway.
+7. Calculate net channel contribution. Include store share, processor and fixed fees, tax or merchant
+   services, refunds, chargebacks, fraud, signing, hosting, bandwidth, review delay, update operation,
+   support, acquisition, and variable product cost.
+8. Derive the break-even lift for each actual price and package. A low fixed-price app, high-price
+   professional app, subscription, and team license can produce different winners; do not embed one
+   fee comparison as a platform law.
+9. Evaluate Windows store, direct, and hybrid paths under current Microsoft policy and actual app
+   type. Store distribution with external commerce can be a candidate where allowed; direct delivery
+   may remain necessary for enterprise, offline, portable, privileged, plugin, or unsupported cases.
+10. Evaluate Mac App Store, notarized direct, and hybrid paths under current Apple policy and actual
+    capability needs. Price store trust against sandbox, commerce, review, licensing, update, and
+    feature constraints rather than assuming either platform has one universal answer.
+11. Keep one application core. Isolate store APIs, direct checkout, licensing, updater, packaging,
+    and policy differences behind narrow channel adapters and shared feature contracts.
+12. Prevent capability drift. Version the channel matrix and compare user-visible features,
+    accessibility, privacy, data formats, account behavior, performance, and support across builds.
+    Differences must be intentional and disclosed.
+13. Define one entitlement model with channel provenance. Preserve store receipt, direct transaction,
+    refund, revocation, subscription status, device or seat, organization, offline lease, and policy
+    version without treating a store login as the product's only customer identity.
+14. Make restoration and duplicate ownership explicit. Cover reinstall, new device, account merge,
+    direct-to-store and store-to-direct migration, double purchase, family or organization access,
+    refund, chargeback, cancellation, and support lookup.
+15. Do not promise cross-channel portability automatically. Decide whether rights can be recognized,
+    exchanged, discounted, grandfathered, or remain channel-bound according to contracts, fraud risk,
+    tax, and platform policy.
+16. Assign update ownership per channel. Store updates, direct updater, enterprise deployment, and
+    manual offline updates need compatible versioning, migration, rollback-forward, support, and
+    release notes; route implementation through `desktop-auto-update-safety-review`.
+17. Account for review and release latency. Cover urgent security fixes, phased rollout, rejection,
+    metadata changes, rollback, customer communication, and channel version skew.
+18. Keep trials and checkout promises channel-aware. State whether trial duration, renewal, refund,
+    coupon, perpetual license, paid upgrade, bundle, and team purchase are available and equivalent;
+    do not hide a weaker channel after acquisition.
+19. Measure self-selection. Direct and store customers can differ in trust, technical ability,
+    geography, price sensitivity, enterprise policy, and acquisition source. Use matched cohorts,
+    staged availability, channel-specific links, or other causal evidence before attributing all
+    outcome differences to the channel.
+20. Judge the full funnel: eligible exposure, listing or landing visit, download, successful install,
+    first owned value, purchase, refund, retained use, update health, support, and contribution.
+    Downloads and gross store revenue are not the headline result.
+21. Promote only a reversible channel policy that improves retained contribution while preserving
+    necessary capability, accurate store and website claims, signing and update safety, entitlement
+    recovery, customer support, and current platform compliance.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Discovery, distribution, commerce, entitlement, update, and support ownership are explicit per
+  channel.
+- Store and direct builds share one product core with bounded, observable channel adapters.
+- Platform capability, sandbox, signing, notarization, policy, commerce, and review constraints are
+  current or explicitly unverified.
+- Purchases can be reconstructed, restored, refunded, revoked, supported, and migrated according to
+  a declared channel policy.
+- Headline channel performance uses retained contribution rather than nominal fees, downloads,
+  listing presence, gross revenue, or update convenience.
+
+<!-- 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`, and
+`mustflow_check`. Do not infer live store, enrollment, signing, notarization, payment, licensing,
+submission, publication, analytics, installer, updater, deployment, or production commands.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If current store policy or regional applicability cannot be verified, mark the channel rule
+  unverified and do not encode it as product behavior.
+- If a store channel removes a core capability, compare a disclosed limited edition or reject the
+  channel; do not hide the loss behind install trust.
+- If entitlement provenance or restore behavior is missing, do not launch a second paid channel that
+  can orphan or double-charge customers.
+- If channel economics omit review delay, support, refunds, signing, update, or acquisition, report a
+  nominal fee comparison rather than a profitability decision.
+- If store and direct builds require diverging product cores, stop and define the missing adapter or
+  intentionally separate product contract before expanding both.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Product, buyer, platform, price, capability, privilege, enterprise, offline, and update needs
+- Direct, store, and hybrid discovery, delivery, checkout, entitlement, update, and support matrix
+- Current policy source and date, sandbox, signing, notarization, review, and channel limitation
+- Gross price, fees, tax, refund, fraud, signing, hosting, update, support, acquisition, retained
+  contribution, and break-even lift
+- Product core, channel adapters, feature parity, receipt, license, restore, portability, migration,
+  duplicate purchase, and version-skew policy
+- Experiment evidence, files changed, command intents run and skipped checks
+- Remaining desktop-commercial-distribution risk
+