mustflow 2.116.4 → 2.117.0

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

@@ -0,0 +1,206 @@
+---
+mustflow_doc: skill.referral-incentive-integrity-review
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: referral-incentive-integrity-review
+description: Apply this skill when a product changes inviter-only, invitee-only, dual-sided, tiered, or milestone referral rewards; referral attribution; invite links or codes; valid-referral qualification; pending, vested, or reversed rewards; self-referral and reward farming controls; rolling thresholds; referral incrementality; or referred-user contribution and must grow without paying for natural signups, fraudulent identities, refundable purchases, or vanity referral counts.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.referral-incentive-integrity-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Referral Incentive Integrity Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Reward incremental, durable referrals without confusing reward direction with tiering, paying both
+sides for disposable signup identities, crediting users who would have joined anyway, or treating
+referred-user revenue as causal growth. Preserve transparent eligibility, reversible reward state,
+privacy, appeals, and unit economics.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A program changes inviter-only, invitee-only, dual-sided, shared-budget, tiered, milestone, cash,
+  credit, discount, premium-time, access, badge, or partner rewards.
+- Invite links, codes, attribution windows, late code entry, pre-existing accounts, channel conflicts,
+  last-click or first-touch rules, or referral ownership change.
+- A valid referral depends on signup, verification, first owned value, retained use, purchase, refund
+  window, subscription survival, or another downstream event.
+- Self-referral, account farms, shared devices, households, payment overlap, refund or chargeback,
+  reward reversal, manual review, appeal, or referral incrementality is implemented or reported.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only changes promotional-credit balance rights, expiry, spend order, or settlement; use
+  `credit-monetization-integrity-review` and `credit-ledger-integrity-review`.
+- The task only changes signup, authentication, identity linking, or onboarding without a referral
+  reward or attribution policy; use `product-onboarding-activation-review` and the identity owner.
+- The task is affiliate, influencer, reseller, creator, sales-partner, recurring-commission, or
+  owned-product cross-promotion policy rather than a customer referral reward; use
+  `growth-distribution-integrity-review` plus the matching payment, tax, contract, and legal owners.
+- The task requests jurisdiction-specific sweepstakes, marketing, tax, privacy, anti-spam, or
+  consumer-law advice. Use current qualified authority; this skill supplies the product evidence.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Actor ledger: inviter, invitee, account age, identity assurance, customer type, geography,
+  household or organization relationship, prior account, prior invitation, eligibility, and consent.
+- Attribution ledger: code or link, issuer, channel, creation and click time, signup and qualifying
+  time, window, priority, late entry, conflicting claims, pre-existing intent, and version.
+- Qualification ledger: verification, first owned value, retained activity, purchase, refund and
+  chargeback horizon, subscription survival, excluded behavior, invalidation, and evidence owner.
+- Reward ledger: recipient, type, face value, expected cost, transferability, expiry, cap, pending,
+  vested, granted, consumed, reversed, appealed, and accounting, tax, platform, or legal review.
+- Tier ledger: valid-referral count, rolling window, thresholds, marginal and cumulative reward,
+  reset, cap, manual review, downgrade, and campaign version.
+- Abuse ledger: identity, device, payment, billing, phone, network, address, behavior and velocity
+  signals, graph links, false-positive risk, reason code, reviewer, appeal, and retention limits.
+- Experiment ledger: eligible population, assignment, no-program or business-as-usual holdout,
+  reward-budget parity, exposure, natural signup, channel cannibalization, horizon, contribution,
+  and promotion rule.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Separate who receives a reward, when it qualifies, when it vests, and how tiers accumulate. These
+  are independent axes.
+- Define the incremental growth outcome and valid-referral event before issuing reward value.
+- Preserve a stable program and attribution version across invite, qualification, vesting, reversal,
+  and appeal.
+- Treat copied split ratios, reward amounts, signup conditions, day counts, tier thresholds, rolling
+  windows, and benchmark lifts as hypotheses, not defaults.
+- Refresh current privacy, identity, messaging, platform, tax, accounting, and jurisdiction rules;
+  this skill does not authorize outbound invitations, live rewards, payments, experiments, or bans.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or refine referral eligibility, attribution, valid-referral qualification, pending and vesting
+  states, reversal, tiering, caps, anti-abuse evidence, appeals, experiment assignment, contribution
+  metrics, fixtures, tests, docs, route metadata, and synchronized templates.
+- Replace signup-only cash-like grants, permanent lifetime tier accumulation, single-signal bans,
+  or gross referred revenue claims with bounded downstream qualification and causal evidence.
+- Do not silently reassign an earned referral, expose private abuse signals, auto-ban from one weak
+  signal, or reverse consumed value without an explicit lawful negative-balance or recovery policy.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Split four decisions: reward direction, qualifying event, vesting and reversal, and tier schedule.
+   Dual-sided and tiered rewards are not competing alternatives.
+2. Define the headline result as incremental contribution per eligible participant or acquired user
+   over a declared horizon. Include reward cost, variable service cost, refunds, chargebacks,
+   support, fraud loss, messaging cost, channel cannibalization, retained value, and later revenue.
+3. Define referral eligibility before attribution. State whether existing accounts, prior visitors,
+   employees, partners, same organization, same household, minors, prior payers, or previously invited
+   users can participate and which actor is ineligible.
+4. Make attribution deterministic. Version code and link ownership, time window, channel priority,
+   late code entry, multiple inviters, cross-device joins, account merges, and pre-existing account
+   behavior. Do not let support choose winners without a recorded rule and audit trail.
+5. Do not equate signup with a valid referral. Choose a downstream event that represents real product
+   value and resists cheap identity creation, such as verified first owned value, retained use, or a
+   payment that has survived the applicable refund and dispute conditions.
+6. Give invitee value when it improves honest activation, but keep it bounded, nontransferable where
+   appropriate, and tied to the product. Delay inviter vesting until the invitee reaches the declared
+   durable condition. This sequence is a candidate, not a universal reward direction.
+7. Keep reward states explicit: proposed, pending, qualified, vested, granted, partly consumed,
+   reversed, expired, appealed, restored, and terminal. Use idempotent identities and preserve the
+   event and policy version that authorized each transition.
+8. Define reversal before launch. Cover failed verification, duplicate identity, refund, chargeback,
+   subscription cancellation, account deletion, policy violation, provider reversal, and later fraud
+   evidence. Separate unvested cancellation from clawing back vested or consumed rights.
+9. Hold economic value only as long as qualification needs. State the expected delay before invite,
+   explain pending status to both actors, and avoid an indefinite fraud-review state.
+10. Compare reward directions at equal expected total budget when the question is who should receive
+    value. If one arm spends more, label it a budget-and-direction test rather than a framing test.
+11. Add tiers only to valid referrals. Use a declared rolling or campaign window, cap, reset, and
+    marginal reward schedule. Do not let lifetime signup count create permanent high-yield farming.
+12. Keep higher tiers economically bounded. Prefer product value with controlled expected cost when
+    appropriate, but include service liability, credit consumption, subscription displacement,
+    transferability, and tax or accounting treatment rather than calling it free.
+13. Detect abuse from multiple consistent signals and behavior. Use identity assurance, device,
+    payment, billing, phone, network, address, velocity, graph, refund, and usage evidence
+    proportionately; one shared IP, device, or household is not sufficient proof by itself.
+14. Design for legitimate collisions. Cover families, schools, offices, shared devices, travel,
+    recycled phone numbers, privacy relays, payment by another household member, and accessibility
+    support. Record reason codes, manual-review thresholds, and an appeal path.
+15. Limit disclosure. Tell users the eligibility or review outcome and actionable remedy without
+    revealing thresholds, graph features, private identifiers, or a recipe for evasion.
+16. Separate invitation delivery from referral attribution. Respect consent, anti-spam, suppression,
+    sender identity, frequency, and channel rules; do not import contacts or message third parties
+    merely because a referral reward exists.
+17. Measure incrementality with a no-program, no-reward, or business-as-usual comparison where
+    feasible. Track natural signup, users who add a code after deciding to join, organic and paid
+    channel displacement, and inviter behavior. Referred-versus-organic revenue alone is observational.
+18. Preserve experiment assignment before reward exposure and keep nonclickers, nonjoiners,
+    unqualified invites, and invalid referrals in the relevant intent-to-treat denominator.
+19. Predeclare guardrails: spam complaints, blocks, privacy requests, false-positive reviews, appeal
+    reversals, account farms, reward cost, refund and chargeback, low-quality activity, support,
+    concentration, and downstream retained value.
+20. Promote only a reversible, versioned program whose incremental contribution and quality improve
+    without paying for disposable identities, natural signups, refundable transactions, or hidden
+    messaging and privacy costs.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Reward direction, valid-referral qualification, vesting, reversal, and tiering remain distinct.
+- Attribution, conflicts, late entry, account merges, and pre-existing users have deterministic rules.
+- Reward states are reconstructable and downstream qualification precedes durable inviter value.
+- Abuse decisions use multiple signals, legitimate-collision handling, bounded review, and appeals.
+- Headline growth uses causal eligible-population contribution rather than raw invites, signups,
+  referred-user revenue, or reward claims.
+
+<!-- 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 reward, credit, payment, identity, messaging, analytics, experiment, deployment, or
+production commands.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If attribution or qualification cannot be reconstructed, pause new vesting rather than guessing
+  the inviter or granting duplicate value.
+- If only signup or referred-versus-organic revenue exists, report acquisition association and do not
+  claim incremental growth or profitable referrals.
+- If abuse evidence relies on one weak signal, keep the reward pending for bounded review or allow it;
+  do not auto-ban without corroboration and an appeal path.
+- If reversal rights for vested or consumed rewards are unresolved, preserve the current right and
+  route future policy to credit, payment, accounting, tax, platform, or legal owners.
+- If higher tiers increase low-quality or fraudulent referrals faster than incremental contribution,
+  cap, reset, or remove the tier rather than optimizing claimed referral count.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Eligible inviter and invitee, attribution, conflicts, window, and program version
+- Valid-referral event, pending period, vesting, grant, consumption, reversal, and appeal
+- Reward direction, equal-budget comparison, cost, transferability, and rights
+- Tier window, thresholds, marginal rewards, cap, reset, and review
+- Abuse signals, legitimate collisions, privacy, messaging, false positives, and reason codes
+- Incremental contribution, natural signup, channel displacement, quality, and guardrails
+- Files changed
+- Command intents run and skipped checks
+- Remaining referral-incentive risk

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.retry-policy-integrity-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: retry-policy-integrity-review
-description: Apply this skill when code is created, changed, reviewed, or reported and retry loops, SDK or client retry configs, backoff, jitter, timeout, deadline, Retry-After, retry predicates, layered retries, circuit breakers, bulkheads, token buckets, queue redelivery, broker retries, cancellation-aware sleeps, or retry observability can amplify failure, duplicate side effects, hide permanent errors, exhaust pools, or overload dependencies.
+description: Apply this skill when code or an agent runtime repeats, repairs, reroutes, replans, or stops after failures and retry loops, prompt correction, model or tool fallback, SDK configs, backoff, jitter, timeout, deadline, Retry-After, retry predicates, layered retries, circuit breakers, queue redelivery, cancellation, or retry observability can amplify failure, duplicate effects, hide permanent errors, or repeat the same unsupported recovery action.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -39,6 +39,9 @@ The review question is not "does this code retry?" It is "when the dependency is
 - Code creates, changes, reviews, or reports retry loops, SDK retry options, client retry middleware, `while true`, `for (;;)`, recursive retry, `maxAttempts`, `maxRetries`, `maxElapsedTime`, `deadline`, `timeout`, `sleep`, `delay`, backoff, jitter, `Retry-After`, circuit breaker, bulkhead, token bucket, rate limiter, or cancellation-aware retry behavior.
 - HTTP, database, Redis, queue, stream, object storage, payment, email, notification, file upload, webhook, scheduler, batch, worker, or provider calls can be repeated after failure, timeout, cancellation, rate limit, lock conflict, transaction retry, or redelivery.
 - A workflow has retries in more than one layer, such as caller retry plus service retry plus SDK retry plus load balancer retry plus queue redelivery plus broker retry.
+- An agent can repeat the same prompt, add validator feedback, choose another model or tool, replan,
+  request more privilege, or stop, and the correct recovery depends on whether new trustworthy
+  information changes the failure mechanism.
 - A review or final report claims a path is resilient, retry-safe, backoff-protected, rate-limit-aware, idempotent, transient-only, bounded, cancellation-safe, or protected by a circuit breaker, bulkhead, pool, timeout, or queue retry policy.
 
 <!-- mustflow-section: do-not-use-when -->
@@ -57,10 +60,17 @@ The review question is not "does this code retry?" It is "when the dependency is
 - Layered retry ledger: caller, API handler, service, SDK, driver, proxy, load balancer, queue, worker, scheduler, and provider retries with per-layer max attempts and elapsed-time budget.
 - Attempt budget: max attempts, max elapsed time, per-attempt timeout, total deadline, cancellation signal, sleep behavior, and whether DNS, TLS, connection checkout, pool wait, request body upload, response streaming, and response parsing are inside the budget.
 - Retry predicate: exception types, status codes, provider errors, timeout classes, rate-limit responses, transient versus permanent failure, unknown outcome, cancellation, validation errors, authorization errors, and programmer bugs.
+- Recovery-action ledger: normalized failure class and signature, new external evidence, same-request
+  retry, corrected-input or prompt repair, alternate model, alternate tool or data source, local or
+  workflow replan, stop or human handoff, expected recovery value, added latency and cost, duplicate
+  risk, remaining budget, and why the action changes the failure mechanism.
 - Side-effect and idempotency ledger: logical operation, idempotency key, key scope, request body hash, conditional write, transaction boundary, lock boundary, provider call, stream or upload body replayability, queue ack or commit, and committed response boundary.
 - Backoff and jitter policy: fixed sleep, exponential backoff, cap, jitter type, `Retry-After` parsing, clock skew, maximum delay, per-key backoff, global backoff, and reset after success.
 - Overload and throttling evidence: pool sizes, concurrency limit, bulkhead, token bucket, circuit breaker state, retry queue size, rate-limit budget, per-tenant or per-key fairness, and dependency-specific limits.
 - Observability and test evidence: attempt logs, per-attempt spans, retry metrics, retry exhaustion metrics, `Retry-After` values, request id, correlation id, cancellation tests, permanent-failure tests, timeout-budget tests, and configured command intents.
+- For model-directed recovery, external verifier evidence, repeated state-action-error signature,
+  route version, tool capability ceiling, plan version, and whether a self-critique or resampling path
+  has an independent way to select the correct result.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
@@ -149,6 +159,31 @@ The review question is not "does this code retry?" It is "when the dependency is
     - Good tests cover permanent failure not retried, max attempts, max elapsed time, total deadline, cancellation during sleep, retry-after parsing and clamping, jitter boundedness, idempotency key reuse, unknown outcome, pool or concurrency limit, and wrapper cause preservation.
     - If deterministic timing tests are hard, use fake clocks, injected sleeper, injected retry policy, or local test helpers already present in the repository.
     - If configured integration evidence is missing, report static risk and the missing manual or integration proof instead of approving the retry path.
+18. Choose among recovery actions, not only retry or fail.
+    - Compare same-request retry, corrected input or prompt, alternate model, alternate tool or source,
+      local replan, workflow replan, stop, and human handoff for the normalized failure class.
+    - Continue only when current evidence says the action has positive remaining value after latency,
+      cost, risk, duplicate-effect exposure, and consumed budgets. Use repository policy rather than a
+      universal attempt count.
+19. Require new trustworthy information for repair loops.
+    - Correct a prompt or model output with compiler errors, failed tests, schema paths,
+      postcondition mismatches, source conflicts, provider status, or another external signal.
+    - Do not treat the same model rereading its own answer, generic "think harder" text, or an
+      unverified critique as new evidence.
+20. Repeat the identical request only when the failure is plausibly transient and the operation is
+    replay-safe, or when independent sampling has an external verifier that can choose a valid
+    result. If no verifier can distinguish candidates, resampling does not establish correctness.
+21. Change model, tool, source, or plan only when it changes the failure mechanism. Switching models
+    cannot repair missing evidence; repeating search cannot repair a stale source without a changed
+    query or source; replanning cannot erase an UNKNOWN external effect.
+22. Stop repeated failure signatures. Hash or normalize the relevant state, proposed action, error
+    class, validator output, and route or tool version. When the same signature recurs without new
+    evidence, stop the local loop and take one declared higher-level recovery or handoff rather than
+    spending the remaining cap blindly.
+23. Keep safety failures attenuation-only. Prompt injection, policy denial, secret exposure,
+    unauthorized tools, and insufficient privilege do not justify a stronger model or wider
+    capability. Isolate the input, narrow tools, return to read or draft mode, request explicit
+    authority, or stop.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -156,6 +191,8 @@ The review question is not "does this code retry?" It is "when the dependency is
 - Retry layers, attempt multiplication, max attempts, max elapsed time, per-attempt timeout, total deadline, retry predicate, backoff, jitter, `Retry-After`, cancellation behavior, side-effect replay safety, idempotency key reuse, transaction or lock placement, pool pressure, throttling, circuit-breaker ordering, wrapper diagnostics, queue overlap, dependency policy, observability, and retry tests are explicit.
 - Infinite retry, broad catch-and-retry, permanent-error retry, unknown-outcome replay, new idempotency key per attempt, fixed-sleep herd behavior, retry inside long transaction or lock, pool exhaustion, app-plus-broker retry multiplication, stale failure counters, wrapper cause loss, committed-response retry, non-replayable body retry, cancellation-ignoring sleep, and missing retry metrics are fixed or reported.
 - Retry-safety claims are backed by configured tests, dependency or framework evidence matched to current code, schema or idempotency evidence, static review evidence, or labeled as manual-only or missing.
+- Model and tool recovery uses external evidence, changes the failure mechanism, preserves the
+  capability ceiling, and stops repeated signatures instead of relying on self-critique loops.
 
 <!-- mustflow-section: verification -->
 ## Verification
@@ -180,6 +217,10 @@ Prefer the narrowest configured test, build, docs, release, or mustflow intent t
 - If a configured command fails, preserve the failing intent, failing assertion or output tail, and the retry invariant it exercised before editing again.
 - If retry layers cannot be enumerated, report that the path is not reviewable for retry amplification yet.
 - If the retry predicate cannot distinguish transient from permanent failure, report the missing classification instead of accepting a broad retry.
+- If no external signal can distinguish a repaired or resampled output from the original failure,
+  stop automatic self-correction and report the missing verifier.
+- If a proposed recovery widens privilege after a tool or policy failure, reject that recovery and
+  require a separate authority decision.
 - If safe repair requires provider idempotency, durable operation records, queue or broker configuration, circuit-breaker architecture, dependency-specific client policy, fake-clock test infrastructure, load testing, or integration replay outside the current scope, report the missing boundary.
 - If deterministic retry proof is not configured, complete available verification and report the missing manual or integration evidence.
 
@@ -188,6 +229,8 @@ Prefer the narrowest configured test, build, docs, release, or mustflow intent t
 
 - Retry policy boundary reviewed
 - Retry surface, layered retry ledger, attempt budget, timeout and deadline, retry predicate, unknown outcome, side-effect and idempotency key, transaction or lock placement, pool and concurrency pressure, backoff and jitter, `Retry-After`, global or per-key throttling, resilience-tool ordering, wrapper diagnostics, committed response or streaming body, queue or broker overlap, dependency policy, observability, and test evidence findings
+- Recovery actions, new external evidence, repeated failure signature, model/tool/source/replan or
+  stop decision, capability ceiling, and self-correction verifier findings
 - Retry-policy fixes made or recommended
 - Evidence level: configured-test evidence, dependency or framework evidence, schema or idempotency evidence, static review risk, manual-only, missing, or not applicable
 - Command intents run