mustflow 1.15.97

package/templates/default/locales/zh/.mustflow/skills/skill-authoring/SKILL.md

@@ -0,0 +1,110 @@
+---
+mustflow_doc: skill.skill-authoring
+locale: zh
+canonical: false
+revision: 3
+lifecycle: mustflow-owned
+authority: procedure
+name: skill-authoring
+description: Apply this skill when creating or maintaining `.mustflow/skills/*/SKILL.md` procedures and `.mustflow/skills/INDEX.md` routes.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.skill-authoring
+  command_intents:
+    - mustflow_check
+    - docs_validate
+---
+
+# Skill Authoring
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Create narrow, repeatable mustflow skill procedures without turning skills into broad advice, project context, or command-permission sources.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A `.mustflow/skills/<name>/SKILL.md` file is created, renamed, split, removed, or substantially changed.
+- `.mustflow/skills/INDEX.md` needs a new or updated route for a skill.
+- A skill needs clearer use conditions, exclusion conditions, required inputs, command intent references, verification, or failure handling.
+- A broad prompt, checklist, or outside recommendation needs to be adapted into mustflow's skill format.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only applies an existing skill to code, docs, tests, context, or assets.
+- The content belongs in `AGENTS.md`, `.mustflow/docs/agent-workflow.md`, `.mustflow/context/PROJECT.md`, or `.mustflow/config/commands.toml`.
+- The proposed skill is broad advice such as "write better code" or "be careful" without a repeatable trigger and procedure.
+- The skill would duplicate project-domain context, authorize commands, install dependencies, or define raw shell commands.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The user request and the repeated task the skill should cover.
+- Existing `.mustflow/skills/INDEX.md` and nearby skill documents.
+- `.mustflow/config/commands.toml` command intent names relevant to verification.
+- Any repository evidence showing that the task is repeatable and not better handled by an existing skill.
+- Localization and template metadata when the skill is part of an installed template.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Required inputs are available, or missing inputs can be reported without guessing.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Keep edits within the scope described by this skill, the user request, and the matching route in `.mustflow/skills/INDEX.md`.
+- Do not broaden command permission, invent project facts, or change unrelated workflow files.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Define the smallest repeatable task the skill should cover. If the task is too broad, split it or leave it as repository guidance instead of creating a skill.
+2. Search existing skills before adding a new one. Prefer updating a matching skill over creating overlapping procedures.
+3. Use a stable folder name and matching frontmatter `name`. Set `mustflow_doc` to `skill.<name>`, `metadata.mustflow_schema` to `"1"`, `metadata.mustflow_kind` to `procedure`, `metadata.pack_id` to the package namespace, and `metadata.skill_id` to `<pack_id>.<name>`.
+4. 编写标准章节：目标、使用时机、不适用时机、必要输入、前置条件、允许编辑范围、流程、后置条件、验证、失败处理和输出格式。
+5. Keep the procedure concrete and bounded. Include what to read, what to change, what to avoid, and what evidence to report.
+6. Reference command intent names only. Do not include raw shell command blocks or claim that the skill authorizes command execution.
+7. 使用紧凑路由更新 `.mustflow/skills/INDEX.md`，其中包含触发条件、所需输入、编辑范围、风险、验证意图和预期输出。
+8. If the skill is installed by a template, update template manifests, localization metadata, installation docs, package tests, and public docs that list installed files.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The expected output can be produced with clear evidence, executed command intents, skipped checks, and remaining risks.
+- Any missing command intent, unknown input, or authority conflict is reported instead of hidden.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `mustflow_check`
+- `docs_validate`
+
+If the skill changes tests or behavior-sensitive template output, also use the relevant configured test or build intents.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If `mustflow_check` reports missing sections, metadata drift, unknown command intents, raw shell commands, or command-permission claims, fix the skill contract before changing unrelated files.
+- If two skills overlap, tighten their use and non-use conditions or merge the duplicate procedure.
+- If a needed command intent is missing, record the missing intent instead of inventing a command inside the skill.
+- If translation confidence is low, keep the source skill authoritative and mark translations for review through template metadata.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Skill files added, updated, renamed, or removed
+- Skill index routes changed
+- Command intents referenced
+- Template or localization metadata updated
+- Command intents run
+- Skipped command intents and reasons
+- Remaining overlap, translation, or validation risks

package/templates/default/locales/zh/.mustflow/skills/source-freshness-check/SKILL.md

@@ -0,0 +1,111 @@
+---
+mustflow_doc: skill.source-freshness-check
+locale: zh
+canonical: false
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: source-freshness-check
+description: Apply this skill when a task depends on information that may become stale, such as current versions, external docs, prices, dates, schedules, or product behavior.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.source-freshness-check
+  command_intents:
+    - changes_status
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Source Freshness Check
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Prevent stale or unverifiable claims from entering code, documentation, templates, release notes, or final reports.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- The task asks for the latest, current, newest, today, yesterday, tomorrow, or a specific recent date.
+- A claim depends on external products, APIs, package versions, pricing, legal rules, schedules, sports, markets, or vendor documentation.
+- Documentation or user-facing text mentions support status, release behavior, command availability, or compatibility that may drift.
+- A source, quote, screenshot, or generated summary may be older than the current task.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The fact is purely local to the repository and can be verified from current files.
+- The task is a mechanical edit that does not introduce or preserve time-sensitive claims.
+- The user explicitly provides the source text to use and asks only for formatting or translation.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The claim or decision that may become stale.
+- The file, command output, source page, screenshot, or user-provided text that supports the claim.
+- The date or version context when it is visible.
+- Any repository policy about allowed sources, official documentation, or offline work.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Required inputs are available, or missing inputs can be reported without guessing.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or update source-date notes only where they clarify freshness risk.
+- Replace unstable wording such as "latest" with a dated or versioned claim when appropriate.
+- Mark translations or docs for review when the source cannot be verified confidently.
+- Do not invent citations, release dates, compatibility ranges, or vendor behavior.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Identify every claim that depends on time, external behavior, or an upstream source.
+2. Prefer the current repository file, official source, declared package metadata, or user-provided source text before secondary summaries.
+3. Capture the freshness boundary: date checked, version checked, release tag, documentation page, or reason the claim is local and stable.
+4. If a claim cannot be refreshed within the allowed tools or command contract, keep the wording conservative and report the unverified source.
+5. Avoid open-ended words such as "latest", "current", or "recent" unless the sentence includes the concrete date or version that makes the claim inspectable.
+6. When editing documentation, keep source notes close to the claim or in the final report rather than adding broad provenance sections.
+7. Run the smallest configured verification that covers the changed files.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Time-sensitive claims are either verified, dated, versioned, or explicitly reported as unverified.
+- Documentation does not imply live freshness when only a snapshot was checked.
+- The final report names skipped refresh checks and any remaining stale-source risk.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Also run the relevant configured test, build, or documentation intent if the refreshed claim changes executable behavior or public documentation.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the requested source cannot be accessed, report the access gap and avoid presenting the claim as current.
+- If sources conflict, prefer the highest-authority source and report the conflict.
+- If the freshness check changes meaning in translated docs, mark the affected translation for review.
+- If checking freshness would require network access or tools outside the current host permissions, stop at the permission boundary and state what remains unchecked.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Freshness-sensitive claims found
+- Source or version checked
+- Wording changed or claim left conservative
+- Command intents run
+- Skipped source checks and reasons
+- Remaining stale-source risk

package/templates/default/locales/zh/.mustflow/skills/state-machine-pattern/SKILL.md

@@ -0,0 +1,214 @@
+---
+mustflow_doc: skill.state-machine-pattern
+locale: zh
+canonical: false
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: state-machine-pattern
+description: Apply this skill when domain objects have lifecycle state, allowed actions depend on state, status changes are scattered, or state transitions need explicit events, guards, effects, history, idempotency, and concurrency control.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.state-machine-pattern
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - test
+    - lint
+    - build
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# State Machine Pattern
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep lifecycle state changes in one explicit rule system.
+
+The state machine pattern applies when an entity moves through meaningful lifecycle states and the allowed actions, errors, follow-up work, or audit expectations depend on the current state. The core artifact is not a class hierarchy. The core artifact is the transition table: current state, event, guard, next state, and effects as data.
+
+Use this skill to prevent scattered `if`, `switch`, direct assignment, silent no-op transitions, duplicate webhook damage, and state changes that bypass audit, outbox, or concurrency rules.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A domain object has three or more states, or fields named `status`, `state`, `phase`, `step`, or `stage`.
+- State determines which actions, API calls, buttons, jobs, events, or commands are allowed.
+- The lifecycle includes cancel, approve, reject, expire, retry, fail, refund, suspend, restore, archive, delete, publish, ship, or deliver flows.
+- State changes must produce history, audit records, domain events, outbox messages, or external effects.
+- Multiple users, workers, queues, webhooks, or external systems can attempt transitions on the same entity.
+- External service results change state and require pending, success, and failure states.
+- Code repeatedly asks whether an action is possible from the current state.
+- State rules are scattered across handlers, repositories, jobs, UI code, adapters, SQL queries, or broad services.
+- Several booleans actually encode one lifecycle and can create impossible combinations.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The value is simple display state rather than domain lifecycle state.
+- The state is a simple two-value toggle with no lifecycle rules, history, side effects, concurrency risk, or irreversible transition.
+- State does not affect allowed actions.
+- The code is a pure calculation, formatter, mapper, parser, or local UI-only state update.
+- A simple create, read, update, delete flow only distinguishes active and deleted and has no meaningful transition rules.
+
+Two states can still require this skill when the lifecycle is meaningful, such as active to suspended to deleted, deleted being irreversible, or suspension requiring audit and authorization.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The entity and state field under change.
+- Complete state list and which states are terminal.
+- Complete event list and the facts each event carries.
+- Current places that change state, validate actions, check state, or render available actions.
+- Guards, authorization facts, time facts, external facts, and loaded domain data needed to decide transitions.
+- Effects, domain events, outbox records, audit records, transition history, idempotency keys, and concurrency protections required by the lifecycle.
+- Existing local patterns for `Result`, events, outbox, repositories, command handlers, pure core decisions, transition tables, tests, and documentation.
+- Relevant command-intent contract entries for verification.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- If changing existing behavior is not the goal, current behavior is protected with tests, fixtures, examples, or explicit verification evidence.
+- If the state-changing operation is a user or system command, `command-pattern` has been used for payload, context, authorization, transaction, idempotency, audit, retry, and outbox execution.
+- If the transition decision is mixed with I/O, `pure-core-imperative-shell` has been used so the transition function stays deterministic and the shell handles persistence and effects.
+- If expected failures or meaningful absence are involved, `result-option` has been used for the error and absence shape.
+- If external services or provider responses influence transitions, `adapter-boundary` and `dependency-injection` have been used before provider facts enter the transition function.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or update state unions, event unions, transition tables, guard functions, effect descriptions, transition result types, and state-machine errors.
+- Replace direct state assignment with a transition function.
+- Add dispatch or shell code that loads the entity, applies the pure transition, saves state, records transition history, stores idempotency records, and writes outbox rows in one transaction.
+- Add available-action helpers derived from the transition table when UI or API callers need possible actions.
+- Add tests for valid transitions, invalid transitions, guard success and failure, terminal states, generated effects, duplicate events, concurrency conflicts, and transition history.
+- Add lifecycle documentation or diagrams only when this repository already documents domain state machines or the changed domain needs an operational reference.
+- Do not create a class hierarchy just to represent states.
+- Do not duplicate the server state machine in UI logic.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Decide whether the lifecycle warrants a state machine.
+   - Apply it when state controls allowed actions, external work, audit, retries, concurrency, or long-running lifecycle behavior.
+   - Avoid it for simple display values and toggles without transition rules.
+2. Replace boolean clusters with explicit state.
+   - Convert combinations such as `isPaid`, `isCancelled`, `isShipped`, and `isRefunded` into one lifecycle state or several independent state machines.
+   - Make states mutually exclusive within one state machine.
+3. Name states by domain meaning.
+   - Prefer states such as `DRAFT`, `PENDING_REVIEW`, `APPROVED`, `PAYMENT_PENDING`, `PAID`, `FULFILLMENT_PENDING`, `SHIPPED`, `DELIVERED`, `CANCELLED`, `REFUND_PENDING`, `REFUNDED`, `EXPIRED`, or `ARCHIVED`.
+   - Avoid UI or placeholder names such as `STEP_1`, `STEP_2`, `BUTTON_DISABLED`, `GRAY`, `READY2`, `TEMP`, and broad states such as `PROCESSING` when a more specific waiting state exists.
+4. Name events as facts that happened.
+   - Prefer events such as `PAYMENT_STARTED`, `PAYMENT_SUCCEEDED`, `PAYMENT_FAILED`, `CANCEL_REQUESTED`, `REFUND_APPROVED`, `SHIPMENT_CREATED`, `DELIVERY_CONFIRMED`, `TIMEOUT_REACHED`, and `EMAIL_VERIFIED`.
+   - Avoid command-like or meaningless events such as `SET_STATUS`, `CHANGE_STATUS`, `UPDATE_STATE`, `MAKE_ACTIVE`, `NEXT`, and `UPDATE`.
+   - Distinguish commands from events: commands request work, events record what happened.
+5. Write the transition table first.
+   - Include every source state, allowed event, guard name, target state, and effect description.
+   - Include terminal states explicitly with no outgoing transitions when they are truly terminal.
+   - Do not hide transition rules inside handler branches, repository filters, database queries, adapter code, or UI code.
+6. Keep guards pure.
+   - Guards may inspect entity state, event data, context facts, loaded external facts, current time passed through context, and authorization facts passed through context.
+   - Guards must not query databases, call SDKs, send messages, write logs, mutate state, read current time directly, generate random values, or trigger external work.
+   - If a guard needs an external fact, load it before transition and pass the normalized fact through context.
+7. Model external work with pending, success, and failure events.
+   - Do not jump directly from request to success for payment, refund, shipment, email, file processing, AI processing, or other external operations.
+   - Use states such as `PAYMENT_PENDING`, `REFUND_PENDING`, `FULFILLMENT_PENDING`, or `ANALYSIS_PENDING`, then model provider success and failure as separate events.
+8. Model time as events.
+   - Expiration, scheduled cancellation, automatic approval, automatic archive, retry window elapsed, and timeout should enter the state machine as events.
+   - Do not scatter direct time checks that assign state outside the transition function.
+9. Keep transition functions pure.
+   - Inputs are entity, event, and context.
+   - Success returns previous state, next state, updated entity or patch, transition log data, domain events, and effect descriptions.
+   - Failure returns a typed error such as invalid transition, guard failed, concurrent transition, or duplicate event conflict.
+   - The pure transition function must not persist, publish, send, call providers, log, read environment variables, read current time directly, or mutate external state.
+10. Separate transition from persistence and effects.
+    - Application or shell code loads the entity, calls the pure transition, and persists the result.
+    - State update, version update, transition log, processed event record, and outbox record should be saved in one transaction when the state is durable.
+    - External effects should run after commit through an outbox, pending effect table, queue, or worker.
+11. Protect durable state with concurrency control.
+    - Use optimistic version checks, compare-and-swap saves, unique constraints, row locks, or conditional updates.
+    - If another transition wins first, return a conflict, reload and recompute, or enqueue a domain-specific retry only when that policy is explicit.
+12. Make duplicate events safe.
+    - Include idempotency keys, provider event identifiers, webhook identifiers, command identifiers, or an equivalent deduplication key.
+    - Same key and same payload should return the prior result.
+    - Same key and different payload should return a duplicate conflict.
+    - Different key with an impossible current state should return invalid transition rather than silently succeeding.
+13. Record transition history when the lifecycle matters operationally.
+    - History should include entity type, entity identifier, from state, event type, to state, actor identifier when known, idempotency key, payload hash, reason when safe, and timestamp from context.
+    - Use transition history for debugging, customer support, dispute handling, audit, and security review.
+14. Derive available actions from the state machine.
+    - UI or API layers may display available actions, but they must not own an independent copy of transition rules.
+    - Prefer a server-side helper that evaluates possible events or exposes allowed actions derived from the transition table.
+    - Treat UI checks as guidance only. Server transition validation remains authoritative.
+15. Split state machines when one state string explodes.
+    - If payment, fulfillment, refund, moderation, or account status change independently, use separate state machines.
+    - State-machine splits require explicit cross-machine invariants, such as fulfillment not shipping before payment succeeds.
+    - Put cross-machine coordination in a domain service, command handler, workflow, or pure policy that calls the smaller machines.
+16. Document only the useful lifecycle contract.
+    - For important domains, document state list, event list, transition table, terminal states, guards, effects, concurrency method, duplicate-event handling, and any cross-machine invariants.
+    - Diagrams are secondary. The code transition table is the source of truth.
+17. Test from the transition table.
+    - Test every valid transition.
+    - Test representative invalid transitions, especially terminal states and dangerous skipped states.
+    - Test guard success and guard failure separately.
+    - Test that successful transitions produce the expected effects or outbox descriptions.
+    - Test that failed transitions produce no effects.
+    - Test duplicate events, duplicate conflicts, transition history, and concurrency behavior when the state is persisted.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- State cannot be changed outside the transition function or dispatch path.
+- Every allowed transition is visible in one transition table.
+- Impossible transitions return explicit errors instead of being ignored.
+- Guards are pure and external facts are passed through context.
+- External work is represented through pending, success, and failure events, with effects executed after persistence.
+- Durable state transitions use concurrency control and duplicate-event handling when needed.
+- Important lifecycle changes leave transition history and outbox or effect records.
+- Tests cover the transition table and the highest-risk invalid, duplicate, and concurrent paths.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `test`
+- `lint`
+- `build`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Choose the narrowest configured verification that covers the changed state machine, dispatch path, tests, templates, docs, release metadata, and mustflow routing.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If states or events are unknown, stop and list the missing lifecycle decisions before coding.
+- If direct assignment remains outside the transition path, report the remaining bypass or finish removing it before claiming the state machine is enforced.
+- If a guard needs I/O, move the I/O to the shell and pass the result as context.
+- If external effects cannot be made reliable through outbox, pending actions, provider idempotency, or compensation, report the reliability gap.
+- If duplicate-event handling is missing for webhook, queue, payment, refund, or worker flows, do not call the transition safe to retry.
+- If a single state machine is becoming unreadable, split independent lifecycle dimensions and document cross-machine invariants.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Entity and lifecycle modeled
+- States, terminal states, and events introduced or changed
+- Transition table location and source-of-truth note
+- Guards and context facts
+- Effects, outbox, history, idempotency, and concurrency choices
+- Direct state assignments removed or remaining bypasses
+- Tests or verification evidence
+- Skipped checks and remaining state-machine risk

package/templates/default/locales/zh/.mustflow/skills/strategy-pattern/SKILL.md

@@ -0,0 +1,215 @@
+---
+mustflow_doc: skill.strategy-pattern
+locale: zh
+canonical: false
+revision: 3
+lifecycle: mustflow-owned
+authority: procedure
+name: strategy-pattern
+description: Apply this skill when code has multiple interchangeable algorithms, policies, calculations, provider choices, scoring methods, sorting methods, recommendation methods, pricing rules, discount rules, shipping methods, notification methods, permission policies, feature-flag variants, or repeated if/switch branches that choose how to do the same kind of work.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.strategy-pattern
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - test
+    - lint
+    - build
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Strategy Pattern
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Separate changeable algorithms, policies, calculations, and execution methods from the stable workflow that uses them.
+
+The strategy pattern applies when several implementations serve the same purpose but differ in how they calculate, decide, rank, price, discount, ship, pay, notify, authorize, search, recommend, or call a provider. The caller should depend on a shared strategy contract, not on concrete implementation branches.
+
+Use this skill to reduce repeated `if` and `switch` branches, keep policy changes out of core flow code, add new variants with minimal existing-code edits, and test each policy independently.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Several implementations do the same kind of work, such as pricing, discounts, shipping fees, payment handling, permission checks, ranking, search, recommendation, notification, file conversion, retry policy, or provider selection.
+- Branches differ by method, plan, region, country, user tier, feature flag, experiment group, input type, provider, format, or business policy.
+- `if`, `else if`, `switch`, `case`, or dictionary dispatch repeatedly chooses the variant and then runs variant-specific logic inline.
+- Adding a new variant requires modifying a central service, handler, controller, command handler, or pure decision function.
+- Variant selection and variant execution are mixed in one function.
+- Variant-specific tests would be clearer than testing one large branching function.
+- A feature would otherwise introduce subclasses, template methods, or base classes just to reuse or swap behavior.
+- Runtime configuration or feature flags choose between old and new algorithms.
+- One variant is an honest no-op, disabled, identity, empty, or zero policy that shares the same contract as real variants.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- There is only one implementation or two stable branches with little chance of growth.
+- Branches perform different user intents or different use cases rather than different methods for the same purpose.
+- Lifecycle state and allowed transitions are the main concern; use `state-machine-pattern`.
+- Object construction is the only thing that varies; use a factory or local construction helper instead.
+- External provider shape, protocol, SDK response, timeout, retry, or error translation is the main concern; use `adapter-boundary`.
+- A state-changing operation needs payload, actor context, transaction, idempotency, audit, retry, and outbox semantics; use `command-pattern`.
+- A caller needs one stable high-level operation that coordinates several dependencies or subsystem steps; use `facade-pattern` and keep strategies only for interchangeable policies inside that workflow.
+- A pure business decision is mixed with I/O; use `pure-core-imperative-shell` first.
+- The strategy variants would combine many independent dimensions into an exploding list of classes; split the dimensions into smaller policies instead.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The stable workflow that needs variable behavior.
+- The variants and the shared purpose they serve.
+- Current branch locations, strategy-like implementations, and selection logic.
+- Common input facts each variant needs.
+- Common output shape and expected failure model.
+- Selection criteria, such as validated user option, server-side policy, config value, feature flag, region, plan, or provider capability.
+- Local patterns for functions, policy objects, registries, dependency injection, decorators, `Result`, tests, and observability.
+- Relevant command-intent contract entries for verification.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- The variants have one shared purpose. If they do not, split the workflow into separate use cases instead of forcing a strategy abstraction.
+- If preserving existing behavior, use `behavior-preserving-refactor` before moving branch bodies.
+- If the strategy depends on external systems, use `adapter-boundary` and `dependency-injection` so provider details stay outside the strategy contract.
+- If normal business failures or unsupported variants are expected, use `result-option` for explicit return and error shapes.
+- If one strategy represents intentional absence or disabled behavior, use `null-object-pattern` to verify that the neutral behavior does not fake success or hide a required failure.
+- If a strategy affects lifecycle transitions, use `state-machine-pattern` for the transition table and use strategies only for replaceable calculations or policies inside that lifecycle.
+- If the strategy is only one part of a larger multi-step subsystem workflow, use `facade-pattern` for the caller-facing workflow and keep the strategy behind its contract.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or update strategy function types, interfaces, policy objects, concrete strategies, selectors, resolvers, registries, decorators, and focused tests.
+- Move inline variant logic from handlers, services, command handlers, or core decision functions into named strategies.
+- Keep simple strategies as functions when they are pure calculations.
+- Use classes only when dependencies, framework injection, complex helpers, or test doubles justify them.
+- Add observability around selected strategy keys when it helps operations and does not leak sensitive data.
+- Do not create broad `Manager`, `Processor`, `Handler`, `Advanced`, `Special`, or `New` strategy names.
+- Do not add strategy ceremony for trivial stable branches.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the branch.
+   - Use strategy when branches choose how to do the same work.
+   - Do not use strategy when branches choose different user intents, object creation only, external shape translation, lifecycle transitions, or command execution units.
+2. Name the strategy family by business purpose.
+   - Prefer names such as `ShippingFeeStrategy`, `DiscountPolicy`, `PaymentCaptureStrategy`, `RecommendationRankingStrategy`, or `PermissionPolicy`.
+   - Avoid vague names such as `Strategy1`, `NewStrategy`, `AdvancedStrategy`, `SpecialStrategy`, `Handler`, `Processor`, and `Manager`.
+3. Define one shared contract.
+   - Fix the input type, output type, and expected error shape.
+   - Keep the input object narrow enough to describe the strategy family, not the entire application context.
+   - Every strategy in the family must accept the same input shape and return the same output shape.
+4. Prefer function strategies for simple pure policies.
+   - Use a function type when the policy is stateless, deterministic, and has no external dependency.
+   - Use a class or object when the strategy needs injected collaborators, configuration, complex helpers, lifecycle management, or framework container integration.
+5. Separate selection from execution.
+   - A selector or resolver chooses the strategy key or strategy implementation.
+   - The strategy executes the variant-specific behavior.
+   - The context or service owns the workflow and calls the selected strategy through the shared contract.
+   - Conditions do not need to disappear; they should move to selection and stop containing variant execution details.
+6. Keep the context ignorant of concrete strategies.
+   - The context may depend on a selector, resolver, registry, or one injected strategy contract.
+   - It should not instantiate concrete strategies or branch on concrete strategy names.
+7. Keep strategy registration discoverable.
+   - Register strategy implementations in one searchable registry, module, dependency-injection assembly, or configuration binding.
+   - Adding a strategy should usually require only a new implementation, registration, and tests, plus a typed key update when the key set is closed.
+8. Treat unknown strategy keys explicitly.
+   - Do not silently fall back when a provided key is invalid.
+   - Distinguish missing optional input that should use an explicit default from unsupported input that should return an error.
+   - Validate user-provided keys before resolving a strategy.
+   - Keep explicit default strategies separate from invalid-key fallback. A no-op or disabled strategy is valid only when it is selected by an explicit rule.
+9. Do not let user input directly select privileged behavior.
+   - A request may contain a desired option, but server-side validation and business rules must decide the final strategy.
+   - This matters for pricing, discounts, payment methods, authorization, shipping, quotas, experiments, and provider selection.
+10. Keep strategies stateless per request.
+    - Store dependencies, immutable configuration, and static lookup data on strategy instances.
+    - Do not store current user, current order, request body, transaction state, intermediate result, or other request-specific data in strategy fields.
+    - Pass request-specific facts through the input object.
+11. Split validation correctly.
+    - Common validation belongs before selection or before strategy execution.
+    - Variant-specific validation belongs inside the strategy.
+    - Expected business failures should return typed `Result` values or local equivalents, not raw strings or normal-flow exceptions.
+    - A no-op, disabled, identity, empty, or zero strategy must return an honest neutral result and must not pretend that a side effect, payment, permission grant, save, upload, or audit record happened.
+12. Avoid strategy combination explosion.
+    - If strategy names grow by combining region, plan, item type, speed, provider, and user tier, split those dimensions into smaller policies and compose them.
+    - Use a composite strategy only when each sub-policy has one clear responsibility.
+13. Keep configuration in the right role.
+    - Configuration may choose a strategy key or enable a feature-flag variant.
+    - Do not hide complex business rules as untyped string expressions in config files.
+    - Feature flags should usually be read by the selector or shell, not inside individual strategies.
+    - Remove obsolete experiment strategies after the experiment ends.
+14. Add observability at the context or decorator boundary when useful.
+    - Record selected strategy key, safe selection reason, duration, outcome, and error code.
+    - Do not log secrets, raw personal data, payment payloads, tokens, or sensitive provider responses.
+    - Prefer decorators for repeated logging, timing, retry, caching, or metrics behavior across strategies.
+15. Test the layers separately.
+    - Strategy contract tests verify every strategy returns the expected shape.
+    - Strategy-specific tests verify each policy's unique behavior.
+    - Selector tests verify which strategy is chosen for each selection condition.
+    - Context tests use fake strategies and verify orchestration, not policy internals.
+16. Refactor incrementally.
+    - Extract one strategy family at a time.
+    - Move existing branch bodies into strategies without changing behavior unless the task explicitly asks for a behavior fix.
+    - Remove dead branches and direct concrete strategy knowledge from the context after tests pass.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Strategy variants have one shared purpose and one shared contract.
+- The stable context no longer contains variant-specific execution branches.
+- Strategy selection is centralized in a selector, resolver, registry, or assembly boundary.
+- Unknown or unauthorized strategy choices fail explicitly.
+- User input is validated before it affects strategy choice.
+- Strategies do not store request-specific mutable state.
+- New variants can be added with minimal changes to existing workflow code.
+- Tests cover strategy behavior, selection behavior, and context orchestration at the right layers.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `test`
+- `lint`
+- `build`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Choose the narrowest configured verification that covers changed strategy code, selectors, registries, tests, templates, docs, release metadata, and mustflow routing.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If variants do not share a purpose, stop and split the use cases instead of forcing a strategy interface.
+- If input or output cannot be made common without a giant dependency object, split the strategy family into smaller policies.
+- If the context still knows concrete strategy names, move that knowledge into a selector, resolver, registry, or assembly root.
+- If unknown keys silently default, replace the fallback with an explicit default case for missing input or an explicit error for unsupported input.
+- If strategy count is growing by combinations, decompose independent dimensions before adding more classes.
+- If a strategy needs I/O but the decision should be pure, move I/O to the shell or adapter and pass normalized facts into the strategy.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Strategy family and shared purpose
+- Contract input, output, and failure shape
+- Strategies added, reused, or deliberately avoided
+- Selector, resolver, registry, or assembly location
+- User-input validation and default behavior
+- State, command, adapter, or pure-core boundaries used with this skill
+- Facade boundary used or intentionally avoided
+- Tests or verification evidence
+- Skipped checks and remaining strategy risk