mustflow 1.18.16 → 1.30.0

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

@@ -1,214 +0,0 @@
----
-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

@@ -1,215 +0,0 @@
----
-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

package/templates/default/locales/zh/.mustflow/skills/structure-discovery-gate/SKILL.md

@@ -1,159 +0,0 @@
----
-mustflow_doc: skill.structure-discovery-gate
-locale: zh
-canonical: false
-revision: 12
-lifecycle: mustflow-owned
-authority: procedure
-name: structure-discovery-gate
-description: Apply this skill before introducing new feature structure, folders, file boundaries, routing, data models, or integration boundaries.
-metadata:
-  mustflow_schema: "1"
-  mustflow_kind: procedure
-  pack_id: mustflow.core
-  skill_id: mustflow.core.structure-discovery-gate
-  command_intents:
-    - changes_status
-    - changes_diff_summary
-    - docs_validate_fast
-    - test_release
-    - mustflow_check
----
-
-# Structure Discovery Gate
-
-<!-- mustflow-section: purpose -->
-## Purpose
-
-Find hidden structure decisions before coding so new files, folders, names, routing, data models, and integration boundaries reduce future change cost instead of producing a neat but brittle tree.
-
-<!-- mustflow-section: use-when -->
-## Use When
-
-- The task asks for a new feature, module, folder layout, architecture, scaffold, refactor, API integration, website, app flow, routing structure, data model, state model, or file split.
-- A named technology or service may be only an implementation choice rather than the product domain, such as AdSense, Stripe, Supabase, Firebase, Resend, SendGrid, Google Analytics, Plausible, or a CMS.
-- The request may hide costly structural decisions around localization, SEO, authentication, authorization, payments, ads, analytics, admin workflows, deployment, content management, storage, retention, or external service replacement.
-- The agent is about to create new top-level folders, shared modules, providers, adapters, services, constants, or public names.
-
-<!-- mustflow-section: do-not-use-when -->
-## Do Not Use When
-
-- The task is a tiny mechanical edit with an obvious target file and no new boundary.
-- The user explicitly asks for a disposable prototype, spike, or one-off example where future structure is out of scope.
-- A structure decision has already been made in current project instructions, accepted design docs, or the immediately preceding user answer.
-- The task is only to match an existing local pattern; use `pattern-scout` unless hidden product assumptions may still change the shape.
-
-<!-- mustflow-section: required-inputs -->
-## Required Inputs
-
-- User request and intended product or code change.
-- Current project instructions, relevant context, and nearby implementation patterns when available.
-- Known target platform, language, framework, package, or deployment constraints.
-- Any named external services, content sources, user roles, locales, data stores, algorithms, policies, feature flags, or revenue surfaces in the request.
-- Risk surfaces that could require a plan/apply gate, capability object, Result or Option return shape, command execution unit, facade entry point, invariant policy, state machine, pure core with an imperative shell, dependency injection boundary, adapter boundary, composition over inheritance, injected clock, state transition table, or idempotency ledger.
-- Optional collaborators whose absence might require a null object, disabled implementation, identity implementation, deny-all policy, or explicit failure.
-- Relevant command-intent contract entries for later verification.
-
-<!-- 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 from current context or can be stated as unknown without guessing.
-- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
-
-<!-- mustflow-section: allowed-edits -->
-## Allowed Edits
-
-- Use this skill to shape the plan, questions, assumptions, file boundaries, and the smallest resulting implementation.
-- Edit only files needed for the accepted or reasonably assumed structure.
-- Do not create broad design documents, policy files, shared folders, provider systems, or abstractions just because they sound tidy.
-- Do not treat this skill as permission to delay every task for a long interview; ask only questions that can change the structure.
-
-<!-- mustflow-section: procedure -->
-## Procedure
-
-1. Restate the requested change as the product capability or code responsibility, not just the named technology.
-2. Identify hidden decisions that could change routing, folder names, file boundaries, data model, state ownership, environment variables, tests, deployment, SEO, localization, external integrations, or legal and policy requirements.
-3. Classify each decision:
-   - Blocking: the answer can change the basic structure and cannot be safely assumed.
-   - Structure-impacting: the answer changes boundaries, but a conservative default can be stated if the user does not answer.
-   - Preference: the answer affects styling, wording, or minor details and should not block structure.
-4. Ask at most five high-value questions before coding. Prioritize localization, authentication, authorization, payments, ads, personal data, destructive data actions, admin workflows, SEO, content storage, and external service replacement.
-5. For any question not asked, state the default assumption briefly. Defaults should keep future changes possible without adding speculative layers.
-6. Select structure patterns only when the task's risk shape requires them:
-   - Use a plan/apply gate for destructive, bulk, migration, billing, permission, publishing, or external-send operations that need review before execution.
-   - Use a capability object when a function should require a specific granted action instead of reading broad user or role state.
-   - Use Result and Option values for expected business failures, meaningful absence, not found, invalid input, denied access, stale state, or blocked policy. Use `result-option` before editing that return-shape contract.
-   - Use a Null Object only when an optional collaborator can safely implement the same interface with honest neutral behavior and the caller should not branch on presence. Use `null-object-pattern` before editing that optional dependency boundary.
-   - Use a command pattern when a state-changing user or system intent needs explicit payload, context, authorization, transaction, idempotency, outbox, audit, retry, concurrency, or queue and worker reuse. Use `command-pattern` before editing that execution unit.
-   - Use a facade pattern when controllers, handlers, workers, command handlers, services, or UI events need one stable high-level entry point over a repeated multi-step subsystem workflow. Use `facade-pattern` before editing that entry point.
-   - Use invariant policy modules when a state change must preserve non-negotiable rules, such as last-owner, paid-order, refund, or entitlement constraints.
-   - Use a state machine when status, state, phase, step, or stage controls allowed events, terminal states, guards, effects, transition history, duplicate-event handling, or concurrency. Use `state-machine-pattern` before editing that lifecycle.
-   - Use a strategy pattern when several algorithms, policies, calculations, provider choices, feature-flag variants, or scoring methods share one purpose and should not keep branching inside the stable workflow. Use `strategy-pattern` before editing that strategy family.
-   - Use pure core with an imperative shell when business decisions, validation, authorization, pricing, eligibility, state transitions, domain events, or effect descriptions would otherwise be mixed with I/O, clocks, generated identifiers, randomness, environment reads, or framework objects.
-   - Use composition over inheritance when behavior varies by multiple dimensions, class inheritance is proposed for implementation reuse, or framework subclasses could stay thin by delegating to explicit collaborators.
-   - Use dependency injection when core logic would otherwise construct, import, resolve, or hide databases, SDKs, clocks, random generators, configuration, loggers, framework objects, filesystems, queues, AI clients, payment gateways, or email senders.
-   - Use an adapter boundary when external APIs, databases, model responses, webhooks, files, queues, caches, framework objects, or command output cross into internal logic or leave it.
-   - Inject time or a time context when expiration, scheduling, retries, leases, or rate windows affect behavior.
-   - Use explicit state transitions when three or more states have meaningful allowed moves.
-   - Use an action ledger or idempotency key when repeating a side effect would be harmful.
-7. Prefer the smallest local version of the selected pattern. Do not add a framework, base class, service locator, global event bus, broad repository layer, or abstract factory when a plain function, table, adapter, or narrow policy object is enough.
-8. Separate product domains from vendor implementations. Use broad names at the product boundary and specific names inside provider or adapter internals.
-   - Prefer `monetization/ads/providers/adsense` over top-level `adsense`.
-   - Prefer `payments/providers/stripe` over top-level `stripe`.
-   - Prefer `notifications/email/providers/resend` over top-level `resend`.
-   - Prefer `analytics/providers/google-analytics` over top-level `googleAnalytics`.
-9. Propose the smallest folder and file structure that follows the answers and assumptions. For each new file or folder, state its responsibility and what it must not contain.
-10. Check the structure against local precedent with `pattern-scout` when the repository already has a nearby pattern.
-11. If the selected structure changes expected failure, meaningful absence, thrown business errors, null returns, or public error mapping, use `result-option` before editing that scope.
-12. If the selected structure creates or repairs a state-changing execution unit, use `command-pattern` before editing that scope.
-13. If the selected structure introduces or repairs lifecycle state transitions, use `state-machine-pattern` before editing that scope.
-14. If the selected structure introduces interchangeable algorithms, policies, calculations, provider choices, or feature-flag variants, use `strategy-pattern` before editing that scope.
-15. If the selected structure introduces one high-level entry point over several subsystem collaborators, use `facade-pattern` before editing that scope.
-16. If the selected structure separates business decisions from execution, use `pure-core-imperative-shell` before editing that scope.
-17. If the selected structure introduces inheritance, base classes, protected state, or subclass variants, use `composition-over-inheritance` before editing that scope.
-18. If the selected structure introduces or repairs an external dependency boundary, use `dependency-injection` for construction and collaborator flow, and `adapter-boundary` for external data, protocol, error, timeout, retry, idempotency, security, and observability handling.
-19. Implement only after the questions, assumptions, structure, dependency direction, and verification surface are clear enough for the task size.
-
-<!-- mustflow-section: postconditions -->
-## Postconditions
-
-- The final structure follows an explicit set of answers or assumptions.
-- Top-level names reflect product responsibilities rather than replaceable vendor names unless the vendor is the product itself.
-- New folders and files have clear responsibilities, non-responsibilities, and dependency direction.
-- Any skipped question, deferred decision, or intentionally narrow assumption is reported.
-
-<!-- mustflow-section: verification -->
-## Verification
-
-Use configured oneshot command intents when available:
-
-- `changes_status`
-- `changes_diff_summary`
-- `docs_validate_fast`
-- `test_release`
-- `mustflow_check`
-
-Also run narrower configured tests or builds required by the changed source, template, documentation, or public contract.
-
-<!-- mustflow-section: failure-handling -->
-## Failure Handling
-
-- If too many structural unknowns remain, ask only the highest-impact blocking questions and report the assumptions that are unsafe to make.
-- If the user does not answer non-blocking questions, proceed with conservative defaults and keep the first implementation small.
-- If a vendor name has already leaked into broad public structure, either localize it inside a provider or report why renaming is out of scope.
-- If a proposed abstraction has only one known use and no likely replacement pressure, keep it close to the feature instead of moving it to shared code.
-- If this skill overlaps with `codebase-orientation`, use orientation to map the existing area first, then return to this skill for the structure decision.
-
-<!-- mustflow-section: output-format -->
-## Output Format
-
-- Capability or responsibility being built
-- Blocking questions asked, or none
-- Structure-impacting assumptions
-- Proposed files and responsibilities
-- Dependency direction
-- Structural patterns selected or intentionally skipped
-- Local pattern used or reason no pattern applies
-- Command intents run
-- Skipped checks and remaining structure risk